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SECTION 2 
LINKER 


a a i, 


The Linker combines separately assembled and/or compiled object units, which can also 
be called compilation units (CUs), and produces a bound unit. An object unit can only be 
executed if it is first linked by the Linker. The Linker executes in either Short Address 
Form (SAF) mode (2 byte-address) or Long Address Form (LAF) mode (4 byte-address). It 
can create, in either mode, a SAF, LAF or SLIC bound unit. A SLIC bound unit can 
execute in either LAF or SAF mode. 

Object units may contain external references to symbols.! While linking object units, the 
Linker resolves external references to symbols by referring to and updating a Linker-created 
symbol table. A link map of defined and/or undefined symbols can be produced: 

To load the Linker into memory, enter the LINKER command (see “Loading the Linker” 
later in this section). 

Linking is controlled by directives entered to the Linker through the directive input 
device. The directive input device is the device specified in the in_ path argument of the 
“enter batch request”’ or “enter group request’? command (normally, the in_ path represents 
a terminal). This device can be reassigned in the command that loads the Linker. 

If the Linker command specifies the —PT argument, the Linker prompter character “‘L?”’ 
will appear each time the Linker expects a directive. 

The Linker processing can be interrupted by: 


| o Depressing the “QUIT’’, “INTERRUPT”, or “BREAK” key on the user terminal 

7 o Entering ACAB group-id on the operator terminal, where group-id is the two-character 
group identification code associated with the group containing the task to be 
interrupted. A **BREAK** message appears on the user’s terminal when the system 
interrupts the Linker. One of the commands SR (start), PI (program interrupt), UW 
(unwind) or NEW-PROC may be entered at this point. SR causes the interrupted task 
to resume at the point where the interrupt occurred (i.e., to continue as if no interrupt 
had occurred). If a MAP or MAPU directive has been issued and the PI command is 
used, the map operation is terminated at its current location and processing jumps to 
the next Linker directive. The UW command causes an orderly termination of the 
Linker processing (i.e., files are closed) and processing continues with some other task 
in the group containing the Linker. 


The NEW-PROC command causes an orderly termination of the task group and the task 
group is reinitialized. 

Each object unit to be processed during a single execution of the Linker must be a 
variable sequential file. The input files may reside in the same directory or in different 
directories. Unless specified otherwise, all of the object units are in the working directory 
(see “Specifying Location(s) of Object Unit(s) to be Linked” later in this section). 

Only one bound unit is created by a single execution of the Linker. A bound unit may 
consist of only a root, or a root and one or more overlays. The root and each overlay may 
be up to 64K words (128K bytes). The root and each overlay is called a load unit; a load 
unit is loaded into memory by the Loader. When you use a create group or spawn group 


( ' An external reference is a reference to a symbol defined in another object unit as an external symbol. 
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command, or an LDBU configuration directive, to request that a bound unit be loaded, the | 
root is the portion of the bound unit that is loaded by the Loader. The root remains in 
memory as long as there are tasks executing on its behalf, unless LDBU was specified; if 
LDBU was specified, the root remains in memory until the system is reinitialized. An 
overlay is loaded into memory whenever it is required. Refer to the Commands manual for a Se a 
discussion of the create group and spawn group commands, and the LDBU configuration 
directive. 

Each bound unit has an attribute table associated with it; an attribute table contains 
information about the bound unit’s characteristics and symbol definitions. The attribute 
table is loaded into eo, immediately preceding the root. 


SUFFIX CONVENTIONS 


For input files, the Linker appends the suffix .O to each specified file name. When you 
specify a file name in a link directive, do not include a suffix. The Linker does not append a 
suffix to the output bound unit name specified in the system command line. 

If a list file is designated (i.e., the -COUT argument is specified in the LINKER 
command), the Linker does not append a suffix to the specified name; otherwise, the Linker 
forms the name of its list file (Linker maps) by appending .M to the specified bound unit 
name. 

Table 2-1 summarizes the formation of file names. 


Program Preparation 
Task 


~ Linker 


TABLE 2-1. DESIGNATING FILE NAMES 


Input File(s) Output File(s) 


Omit suffix. Linker Omit suffixes. The Linker appends .M to specified 
appends .O to each bound unit file name to form the name of the list file 
specified file name. if the -COUT argument was not specified in the LINKER 
command. The Linker does not append a suffix to the 
name designated in the -COUT or -IN directives, nor to 
files named in the IN or LIB(x) directives. 


FUNCTIONS OF THE LINKER 


Creating a Bound Unit 

The Linker produces a bound unit file whose pathname is specified in the name argument 
of the LINKER command. 

The bound unit comprises only a root unless an OVLY or FLOVLY directive is entered. 
Each time an OVLY or FLOVLY directive is entered, the Linker initiates creation of a 
nonfloatable or floatable overlay, respectively. A nonfloatable overlay is loaded by the 
Loader into the same memory location (relative to the root) each time it is requested. A 
floatable overlay is linked at relative 0 (see “BASE Directive” later in this section), and can 
be loaded by the Loader into any available memory location. A floatable overlay must have 
the following characteristics: 


_ 1. External location definitions in the overlay are not referenced by the root or any other 
overlay. 


2. There cannot be external references between floatable overlays. 
3. The overlay does not contain external references that are not resolved by the Linker. 
4. The overlay must be linked after all desired nonfloatable overlays have been linked. 
5. The overlay cannot contain P+DSP references to any other overlay or the root. 
6. The overlay cannot contain IMA Gmmediate memory address) references within itself. 
7. There can be IMA references (with or without offsets) to locations in the root or any 
nonfloatable overlay. | | pre, 
eo 
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NOTE: When the lowest address of a root or overlay has been established (i.e., an object 
unit has been linked), it is illegal to define a lower BASE address within that root 
or overlay. 


START specifies the relative address at which the root or overlay will begin executing 
when it is loaded into memory by the Loader. 

IST identifies the beginning of initialization code in the root. 

SHARE designates that the bound unit is shareable. 

SYS designates that the bound unit can be loaded into the system area as part of the 
system. | 

LINK, LINKN and LINKO specify which object units will be linked. The order in which 
specified object units are linked, and when they are linked, is determined by which link 
directive is specified. 

OVLY names and assigns a number to the next nonfloatable overlay that follows, and 
designates the end of the preceding root or overlay. 

FLOVLY names and assigns a number to the next floatable overlay that follows, and 
designates the end of the preceding root or overlay. 

Call-cancel (CC) permits a COBOL program that used CALL and CANCEL statements to 
call overlays by their names. 

QUIT designates that the last Linker directive has been entered. Execution of the Linker 


-terminates after the bound unit has been created. 


Producing Link Map(s) 


Directives: 
MAP 
MAPU 


A link map is written to the list file by specifying the MAP or MAPU directive. MAP 
creates a map that lists both defined and undefined symbols, whereas MAPU lists undefined 
symbols only. 


Defining External Symbol(s) 


Directives: 
COMM 
LDEF 
VAL 
VDEF 
EDEF 


The COMM directive defines a symbol as being labelled or unlabelled common.” 

A symbol can be defined as a relative location or value by specifying the LDEF or VDEF 
directive, respectively. The symbol’s definition is then put into the symbol table by the 
Linker. 

The VAL directive specifies a value definition at LINK time. This value is equivalent to 
the difference between two external locations. 

The EDEF directive permits definitions in the Linker symbol table to be made part of the 
bound unit so they are available to the Loader at execution time. 


* For discussions of “common” see the appropriate language reference manual. 
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Protecting or Purging Symbol(s) 


Directives: 
CPROT 
CPURGE 
PROT 
PURGE 
VPURGE 


The CPROT and CPURGE directives, respectively, protect and remove symbols associated 
with labeled and unlabeled common. 

The PROT and PURGE directives, respectively, protect and remove symbols and object 
unit names from the symbol table. 

The protect (PROT) directive prevents certain symbols and/or object unit names from 
being removed from the symbol table. Symbols are protected if they identify a specified 
address or an address within a specified range; object unit names are protected if they are 
equated to a specified address or an address within a specified range. 

The PURGE directive removes from the symbol table unprotected symbols that define a 
specified address or an address within a specified range, and/or object unit names equated to 
a specified address or an address within a specified range. 

The VPURGE directive removes a specified value definition from the symbol table. 


Designating That the Last Linker Directive Has Been Entered 


Directive: 
| QUIT 


QUIT must be the last Linker directive entered. 

If a bound unit is being created, execution of the Linker terminates after the bound unit 
has been created. 

If no bound unit is being created, QUIT terminates setaton of the Linker. 


LOADING THE LINKER 


To load the Linker, enter the LINKER command, which is described below. 
After the Linker is loaded, there is a typeout to the error output file of the revision also 
in the following format: 


LINKER-nnnn-mm/dd/hhmm 


where nnnn is a release identification, mm/dd is the month and day the Linker component 
was linked, and hhmm the time (hour, minutes) at which that link took place. 


FORMAT: 
LINKER bound-unit-path [ctl arg] 
ARGUMENT DESCRIPTIONS: 
bound-unit-path 
Pathname of the relative disk bound unit file. The pathname can be simple, relative, or 
absolute and must be preceded by a space. If the specified file already exists, the 


existing information in the file is deleted and replaced with the new bound unit. The 
bound unit pathname must be specified. It may be up to 62 characters in length. 
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ctl arg 

Control arguments; none or any number of the following control arguments may be 

entered, in any order: 

-IN path 
Pathname of the device through which Linker directives will be read; can be disk, 
card reader, operator’s terminal, or another terminal. 
Error messages are written to the error output file. Linker error messages are 
described in the System Messages manual. 


Default: Device specified in the in_path argument of the “enter batch request” or 
‘enter group request” command. 


When this argument is specified, the prompter character will not appear. 


-PT 
If the -IN argument is not specified, -PT can be specified in order to produce a 
prompter character on the user terminal. A prompter character is issued only if -PT 
is specified. 

-COUT list-path-name 
Designates the list file. The list file can be sent to a disk, another terminal, or a 
printer. The list-path-name is associated with this list file. If -COUT is not specified, 
the list-path-name has a default value of bound-unit-path .M. 

{ -LAF 

ee 

-SLIC 

LAF and SAF are addressing modes in one of which the bound unit is to execute; 
-LAF designates long address form (two-word addresses); -SAF designates short 
address form (one-word addresses); -SLIC designates that either a SAF or a LAF | 
machine may be used with no reassembly or link necessary. | 
Default: Bound unit executed in SAF (short address form) mode. 


-SIZE nn 

-SZ nn 
nn designates the maximum number of 1024-word (1K) blocks of memory available 
for the Linker symbol table; nn must be from 1 to 32. At least 1024 words must be 
available. 


Default: 2K 
-W 
Specifies that the implicit Linker work files are to be saved. 


Default: Implicit Linker work files are automatically released by the Linker upon 
Linker termination... 


-R 
Designates that a bound unit is to be created, where all data areas defined as 
common are separated from all other code. Required for shareable CU’s (object 
units). 


-VERBOSE 
Causes all Linker directives to be printed on the list file. 


-NOMAP 
Suppresses the list file. 


Example: 


LINKER MYPROG-INA MYDISK>CNLA-COUTA>SPD>LPTO0A-SIZEA06 
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This LINKER command loads the Linker and designates the following: 


0 Bound unit will be a relative file named MYPROG in the working hedioee 
o Linker directives will be entered through disk file ‘MYDISK>CNL. | 
o List file goes to a line printer (configured as LPTOQ), rather than to a variable Se 

sequential file named MYPROG.M in the working directory. 
o The symbol table will be a maximum of 6K words of memory. 


NOTE: LPTOO must have been previously defined in the DEVICE configuration 
directive, which is described in the “Startup and Configuration Procedures” 
section of the System Building manual. 


ENTERING LINKER DIRECTIVES 


Linker directives are entered through the directive input device, except for the following 
directives which may be embedded in assembly language CTRL statements: LINK, LINKN, 
LINKO, SHARE, EDEF, and SYS. 

Linker directives comprise only a directive name or a directive name followed by one or 
more parameters. Each directive name may be preceded by 0, 1, or more blank spaces, If 
one or more parameters are to be specified in a Linker directive, the directive name must be 
immediately followed by one or more blank spaces. 

Multiple directives can be entered on a line by specifying a semicolon(;) after each 
directive, except for the last directive on the line. 

The last (or only) directive on a line can be followed by a comment; to include a 
comment, specify a space and a slash (/) after the last (or only) parameter and then enter 
the comment. | 

If the directive input device is the epee s terminal or another terminal, press 
RETURN at the end of each line (i.e., at the end of the comment, or at the end of the last 
directive if there is no comment). 

If an error occurs when entering a directive, an error message is written to the error 
output file. Linker error messages are described in the System Messages manual. Determine 
what caused the error, and then reenter the directive correctly. If multiple directives are — 

-entered on a line and an error occurs, the error does not affect the execution of previously 
designated directives. The directive that caused the error and subsequent directives on that 
line are not executed. 


PROCEDURE FOR CREATING ONLY A ROOT 


To link object units and create only a root, load the Linker and then enter the following 


directives: 
LINK }? | 
LINKN Links object units. 
(\LINKO] 
QUIT Designates that the last Linker directive has been entered. After the 


bound unit has been created, execution of the Linker terminates. 
All other directives are optional. 


PROCEDURE FOR CREATING A ROOT AND ONE OR MORE OVERLAYS 


When creating a root and overlays, the following rules must be followed: 


o The root must be created before its overlays. 
o A root and all of its overlays must be created during the same Secuion of the Linker. 


3 Multiple LINK and/or LINKN and/or LINKO directives may be entered. . mee 
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o Nonfloatable overlays must be created before floatable overlays. 
o Overlays may contain references to symbols defined in the root or other overlays. 
o Aroot or overlay can be up to 64K words of memory. 


To link object units and create a root and one or more overlays, load the Linker and then 
enter the following required directives: 


LINK {4 

LINKN Links object units that will constitute the root. 

LINKO | 

OVLY Designates end of the root, and names and numbers the overlay that 
FLOVLY immediately follows. | 

LINK Links object units that will constitute an overlay. 

LINKN 


NOTE: An OVLY or FLOVLY directive and at least one link directive must be specified 
for each overlay associated with the root. 


QUIT Designates that the last Linker directive has been entered. After the 
| bound unit has been created, execution of the Linker terminates. 


All other directives are optional. 


NOTE: It is advisable to specify a MAP directive before each FLOVLY directive. The 


base address of a floatable overlay is relative 0, so all unprotected symbols that — 


define locations will be purged from the symbol table. 


PROCEDURE FOR CREATING A SHAREABLE BOUND oe 
USING A HIGH-LEVEL LANGUAGE 

A shareable bound unit (BU) is one in which the code portion resides in system memory 
and can be used on behalf of one or more groups to manipulate data in that group. To 
accomplish this, the following factors must be present: 


1. The pure (4.e., code) portion of the bound unit must be separated from the impure 
(i.e., data) portion. 

2. The BU must be declared shareable. 

3. Space must exist in the System pool to allow loading of the pure portion of the BU. 


These factors are processed respectively as follows: 


1. Using the capability to declare pure portions from impure portions (e.g., Intermediate 
COBOL), specify the -R argument on the Linker command line. This will cause the 
Linker to separate all those items declared as impure from the rest of the program. 

2. Specify the SHARE directive for the BU at link time. 

3. If both of the preceding conditions are specified, the Loader will automatically load 
the pure section of the BU into the System space in memory. If not enough room 
exists in the System space, the pure section will go into the group with the impure 
section and will no longer be shareable. 


Using the Intermediate COBOL compiler, which automatically puts data in “‘Local 
Common’’, or using the Assembly Language pseudo-operator ($LOCOMW), the capability to 
Share a pure code portion of a program exists. If the -R argument is specified at link time, 
the resultant BU can be up to 128K (up to 64K for pure code and up to 64K for data). 


* Multiple LINK and/or LINKN and/or LINKO directives may be entered. 
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No overlays are permitted in a shareable/separated BU. 

When the -R argument is specified, all data which the compiler defines in common is 
separated from executable code. All references in the code to this data are made via peeree 
$B6. The data does not directly reference the code. 

When the -R argument is not specified, overlays are permitted. In this case, the maximum 
size of the root or of any individual overlay is 64K (including both code and data). 


OBTAINING SUMMARY INFORMATION OF A LINKER SESSION 


The Linker designates on the list file summary information regarding the bound unit 
created during the current execution of the Linker. 

The list file includes the name of the bound unit and date and time of link, the name and 
revision number of each object unit linked, the name of the seseqabler/compiler, the 
assembler or compiler error count, and the sections described below: 


ROOT Name of the root. 

HIGHEST OVLY Number of the last overlay> ; if there are no 
overlays HIGHEST OVLY is followed by a 
blank. | 

/NUM OF SYMS Number of symbols specified: in EDEF 

: directives. 

SAF Type of addressing form used in the bound 

LAF unit; SAF is short-address form, and LAF is 

SLIC long-address form. 

A SLIC bound unit may be executed in either 
SAF or LAF mode. 
ped Name of the root or overlay. 

OVLY 

BASE | Base address of the root or overlay. 

ST Start address of the root or overlay. 

SFUI Specifies characteristics of the bound unit, as 
follows: 

S 


Shareable bound unit. 


Floatable overlay(s) included. 
U 
There are resolved or unresolved forward references between the root and overlays or 
between overlays. 
J 
IMA addresses are present. 


HIGH © Highest address in the root or overlay. 


*SIZE OF ROOT AND STATIC OVLYS Highest address in either the root or the 
largest overlay. (Indicates the amount of 
memory needed to load the bound unit.) 

HI REL RCD The number of the highest relative record of 

~ the bound unit file. (Indicates the number of 
control intervals used for storage.) 

LINK DONE 

Designates that execution of the Linker has been successful. 


‘The Linker assigns numbers to overlays. The first overlay is 00; subsequent overlays are numbered sequentially in ascending 
order. 
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The format for this information is illustrated below: 


ROOT rootname 
HIGHEST OVLY number/NUM OF SYMS number 


oF 8 OK OK OK OK ok eK 


SAF 
LAF 
SLIC 


36 28 oh 36 Ko 2 OK Ok Ok 


CMMN® |rootname BASE address ST address -.... HIGH = high address of data ; 
poses dirname + overlay a BASE address ST address - ie ‘4 +n WI : 


OVLY 
HIGH = high address of root or overlay 


OK OK 2K oe ok ok oe ok ok 2 


*SIZE OF ROOT AND STATIC OVLYS = number,, HI REL RCD = number; 9 


7K oR 6 2 of ok ok OK of ok 


LINK DONE 


oF ok OK 2 2 ok 2k OK RK ok 


LINKER DIRECTIVE DESCRIPTIONS 


Linker directives are described below, alphabetically. Some examples are provided to 
illustrate directive usage. 


BASE Directive 

The BASE directive defines, for subsequent object units to be linked, the relative link 
address within the bound unit. At load time, all addresses are relative to the beginning of 
available memory (relative 0) in the memory pool of the task group. When a task group is 
created, you specify the memory pool into which its bound units are to be loaded. 

Unless BASE directives specify otherwise, the root will be linked, by default, at relative 0, 
and subsequent object units are linked at successive relative addresses. A BASE directive can 
be used at any point during linking to change the relative locations of the root, overlays, or 
individual object units. A floatable overlay always begins at relative 0; therefore, in a 
floatable overlay, BASE can be specified only after the first (or only) LINK, LINKN or 
LINKO directive. A BASE argument can specify a previously used or defined location, or 
an address relative to the beginning of the available memory. 

If unprotected symbols define locations that are equal to or greater than the location 
designated in the BASE directive, those symbols are removed from the symbol table. 


FORMAT: 


$ 
% 
X ‘address’ 
=object-unit-name 
xdef | mA X‘ofiset’| 


# The current address. 


BASE 


6If —R argument is specified and common exists. 
7 This line is repeated for each overlay. 
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BASE 
ARGUMENT DESCRIPTION 


$ 
Next location after the highest address of the linked root or previously linked sien float: 
able overlay. 


% absolute 
Highest addresst+] ever used in the linked root or any previously linked sontioatable 
overlay. 


address » 2 | 
Hexadecimal address comprising one to fous integers enclosed in apostrophes and 
preceded by X. The specified address is relative to the Peerimne of available memory 
(relative 0) in the memory pool at load time. 7 


=object-unit-name | 
Specified object unit’s base address; the subsequent root, overlay, or object unit will be 
linked at the same relative address as the specified object unit, which must have already 
been linked. Furthermore, the object unit name must still exist in the symbol table 
(i.e., it isnot purged). — 


xdef [{* \X‘offset” 


Address of any previously defined external symbol. If an offset is specified, it must be 
a hexadecimal integer with an absolute value less than 8000 (32768 decimal). 


Default: 
Root—0 
Nonfloatable overlay-Next location after the highest address of the preceding root or 
nonfloatable overlay | 
Floatable overlay—O 


Example: - 


This example illustrates usage of BASE directives in a bound unit that comprises a root and 
overlays. In this example, assume that the bound unit being created is going to be executed 
as part of task group Al, and memory pool AA is to be used by this task group. Figure 2-1 
illustrates memory pool AA’s location in memory relative to the system pool and another 
pool, and the locations within that memory pool to which each object unit specified in the 
following directives will be loaded. 


LINKER TEXTA-COUTA>SPD>LPTO0. Designates address at which execution will begin 


START TEXTEN when the root is loaded. 
IST INIT | Defines INIT as the beginning of initialization 
code. — 
LINK OBJ1,OBJ2 | Request that OBJ1.0 and OBJ2.0 be linked. 
MAP 7 ~ Causes OBJ1.0 and OBJ2.0 to be linked, and 
: a produces a link map. 
OVLY ABLE 3 Designates end of the root, and that a nonfloat- 


able overlay named ABLE immediately follows. 
The Linker assigns the number OO to this 
overlay. 
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CALL-CANCEL/COMM/CPROT/CPURGE 


cc (Call-Cancel) Directive 


The call-cancel directive (CC) must be used when linking COBOL programs that contain 
CALL/CANCEL statements that reference overlays. The Linker will place each overlay 
name and its associated Linker-generated overlay number into the bound unit attribute table 
so that the COBOL program can call/cancel overlays by name. 

To support the CALL/CANCEL facility, the object unit ZCCEC is required. ZCCEC will 
be automatically linked into the root; it requires no link directive. 

The CC directive must be specified before the first LINK, LINKN or LINKO directive in 
the root. 


FORMAT: 
CC 

COMM Directive 

The COMM directive defines a labelled or unlabelled “common” area of a specified size. 
FORMAT: 

COMM symbol, size 

ARGUMENT DESCRIPTION: 

symbol 


Identifies the external symbol which is to be treated as common. 

size 
Size is specified as a 1- to 4-character hexadecimal number bound by single quotes and 
preceded by the letter X (i.e., X’size’). — 


CPROT Directive 
The CPROT directive prevents specified symbols from being removed from the common 
area, 
FORMAT: 
CPROT symbol 
ARGUMENT DESCRIPTION: 
symbol 
Name of the external symbol, that is to be protected. The symbol must be specified in 
the COMM directive, or defined as common at the time of assembly or compilation. 
CPURGE Directive 
The CPURGE directive causes the Linker to remove an unprotected symbol from the 
common area. 
FORMAT: 
CPURGE symbol 
ARGUMENT DESCRIPTION: 


symbol 
Identifies the external symbol which is to be removed from the common area. 
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EDEF 


EDEF Directive 

The EDEF directive causes the transfer of a symbolic definition from the Tikes to the 
Loader at load time. The bound unit attribute table is part of the bound unit. | 

An EDEF directive can only specify a symbol that has been defined using XDEF, LDEF, 
or VDEF. When EDEF is specified, the symbol’s definition must already be in the symbol 
table. 

Secondary entry points of bound units, whose ee is to necute under control at a task, 
must be defined in an EDEF directive. This includes secondary entry points of overlays and 
the root entry point when it will be explicitly used in a create group command. The start . 
address of the root and of each overlay is placed by the Linker in the bound unit arembure 
table and does not need an EDEF definition. 

If a bound unit is memory resident, symbols (entry points and references) can be denned | 
by EDEF so that they can be referenced by any bound unit loaded by the system. At 
system configuration time, when the resident bound units are loaded using the LDBU 
system configuration directive, these symbols are placed in the system symbol table. When 
the Loader loads other bound units that contain unresolved references, it tries to resolve 
them with the list of symbols defined for resident bound units. 

If the bound unit is transient (shareable or not shareable), the symbols in the attribute 
table of the bound unit are meaningful only as definitions of secondary entry points. 
Although shared bound units can be in the address space of more than one task group, the 
bound unit attribute table is available to the Loader only when the bound unit is being 
loaded. Unresolved references in any bound unit will be resolved only to symbols defined in 
attribute tables of resident bound units. 

The EDEF directive can be embedded in assembly language CTRL statements. 


FORMAT: 
{ EDEF' symbol 
ARGUMENT DESCRIPTION: 
symbol 


Any external definition comprising one to six characters. The symbol must have been 
defined. If the symbol was multiply defined, the first definition is used. _ 


Example: 
This example illustrates usage of EDEF directives in bound units. 
LINKER MYPROG Loads the Linker. The bound unit named MYPROG 


will be created on the working directory. The list file 
MYPROG.M is also created on the working directory. 


LINK A 

LINKN B 

MAP 

EDEF B B is a symbol defined as an external location or value 
in B.O, ~ 

LDEF SYM,X’1234’ Assigns relative location 1234 to external symbol 
named SYM. 

OVLY FIRST Designates end of root, and names nonfloatable 


overlay that immediately follows. 
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EDEF/FLOVLY 


LINK X,Y 
EDEF SYM 


QUIT Designates that the last Linker directive has been 
entered. Execution of the Linker terminates after the 
bound unit has been created. 


LINKER PROG? -COUT >SPD> Loads the Linker; the bound unit to be created is 


LPTOO -SIZE 02 named PROG2. The list file is the printer. The 
symbol table is a maximum of 2K words of memory. 
BASE X?2222’ Subsequent object units will be loaded into memory 
| starting at the relative address 2222. 
LINKN W Requests that object unit W.O be linked. 
MAP Produces a link map; in this map, it is determined 


that object unit W.O contains an unresolved reference 
to the symbol SYM, which was defined in the root of 
the bound unit MYPROG. 


QUIT 


If MYPROG is loaded into memory via an LDBU configuration directive, when the 
Loader loads PROG2 the Loader will resolve the unresolved reference in PROG2 to the 
symbol SYM, which was defined in the root of MYPROG. 


NOTE: An EDEF directive cannot be entered on the directive line in which the object 
unit is specified. For example, if the symbol TAG is defined in object unit A, the 
following directive line is not allowed: 


LINK A:EDEF TAG 


FLOVLY Directive 

The FLOVLY directive assigns the specified name and a number to the floatable overlay 
that immediately follows, and designates the end of the preceding root or overlay. The 
characteristics of floatable overlays are described earlier in this section under ““Creating a 
Bound Unit.” 

FLOVLY must be specified as the first directive of each floatable overlay. Floatable 
overlays must be linked after all desired nonfloatable overlays have been linked. 

The Linker assigns a two-digit number to each overlay. Overlays are numbered 
sequentially, in ascending order; the first overlay is 00. 


FORMAT: 
FLOVLY name 
ARGUMENT DESCRIPTION: 
name 


Name of the floatable overlay that immediately follows. The overlay name must 
comprise one to six alphanumeric characters; the first character must be alphabetic. 
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FLOVLY/IN 


Example: 

LINKER BU Loads the Linker and designates BU as the bound 
: unit name. 

LINK A 

LINK B | | | 

MAP | Produces a link map. The link map should be 


referenced to determine if there are any unprotected 
symbols that define locations. These symbols, if any, 
will be removed from the symbol table since the 
floatable overlay that immediately follows has a 
default base address of 0. 


FLOVLY GR Designates the end of the root (which comprises 
object units A.O and B.O), and specifies that the next 
overlay is a floatable overlay named GR. The Linker 
assigns the number 00 to this overlay. 


LINK X 

LINK Y 

MAP | 

FLOVLY BR Designates the end of floatable overlay GR, and 
designates that the floatable overlay that immediately 
follows is named BR. The Linker assigns the number 
Ql to this overlay. _ 

LINK R6 

MAP 

QUIT 


IN Directive | 

The IN directive designates a different directory as the primary directory.® This directive 
permits the linking of object units that are in directories other than the default primary 
directory or secondary directory (if any). If the IN directive is not specified, the working 
directory is the primary directory. (The secondary directory is designated in the LIB 
directive.) 


NOTE: The IN directive must be specified before the first LINK, LINKN or LINKO 
directive that requests the linking of an object unit that is in the specified 
directory. 


The specified directory remains the primary directory until another IN directive is 
entered. If the primary directory is changed via an IN directive and at a later time you want 
the task group’s working directory to be the primary directory, you may enter the IN 
directive and omit a pathname. 

FORMAT: 


IN [path] 


*The primary directory is the first directory that the Linker searches for the specified object unit(s) to be linked. 
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ARGUMENT DESCRIPTION: IN/IST 


[path ] 
Pathname of the directory being designated as the primary directory. The pathname 
may comprise a maximum of 64 characters. A simple, relative, or absolute pathname 
may be specified (methods of designating pathnames are described in the Program 
Preparation manual). If path is omitted, the working directory becomes the primary 
directory. This argument may not be embedded in source code (CTRL). 


Example |: 


INA*DIR>PRIM 


This directive designates that “~DIR>PRIM is the primary directory. 
Example 2: 
This example illustrates usage of the IN directive in conjunction with directives that request 


the linking of object units. Assume the primary directory is the working directory, whose 
relative pathname is WORK>CURR; object units X.0, Y.O, and Z.O are in the working 


directory. 

LINKER OUTPUT Loads the Linker; a bound unit named OUTPUT will 
be created on the working directory. 

LINK X Requests the linking of object unit X.O; X.O is in the 
working directory. 

INA*NEW>PRIM Designates that ~NEW>PRIM is now the primary 
directory. 

LINK A Requests the linking of object unit A.O, which is in 


the primary directory. “NEW>PRIM>A.O is the 
pathname of A.O, as expanded by the Linker. 

LINK C Requests the linking of object unit C.O, which is in 
the primary directory. “NEW>PRIM>C.O is the 
pathname of C.O, as expanded by the Linker. 


IN WORK>CURR Designates that the primary directory is now the 
working directory. 
LINKN Y Requests the linking of object unit Y.O, which is in 


the working directory. WORK>CURR>Y.O is the 
pathname of Y.O, as expanded by the Linker. 

MAP 

QUIT 


IST Directive 

The IST directive identifies the beginning of initialization code in the root. Initialization 
code is to be executed once only, immediately after the root is loaded. After the 
initialization code is loaded, the space may be made available for overlays. The IST directive 
is meaningful only when associated with an LDBU directive that specifies an initialization 
subroutine table (IST). LDBU, a CLM directive, is explained in the System Building manual. 


FORMAT: 
IST external symbol 
IT 


ARGUMENT DESCRIPTION: 


external symbol 
Symbol specified by label in IST section of LDBU. 
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LDEF 
LDEF Directive 7 

LDEF assigns a relative Jocation to an external symbol. A symbol should be defined only 
once, either as a location or as a value. When a symbol is defined, its definition is put into 
the Linker symbol table so that it can be used to resolve references to the symbol during 
linking. When a symbol defined as a location is no longer referenced, its symbol table entry 
can be cleared by specifying the PURGE directive. PURGE has no effect if a protect 
(PROT) directive was previously specified. 


FORMAT: 
$ 
% 
X ‘address’ 
LDEF =object-unit-name 
LF symbol, 
xdef i * X‘oftser' 
# , 
ARGUMENT DESCRIPTIONS: 
symbol 
One to six alphanumeric characters. 
$ 


Next location after the highest address of the linked root or previously linked 
nonfloatable overlay. 


% | 
Highest addresst1 ever used in the linked root or any previously linked nonfloatable 
overlay. 


address | 
Hexadecimal address comprising one to four integers enclosed in apostrophes and 
preceded by X. The specified address is relative to the beginning of available memory 
(relative 0) in the memory pool. 


=object-unit-name 
Specified object unit’s base address. 
xdef| {*} X ‘offset’ | 


Address of any previously defined external symbol. If an offset is specified, it must be 
a hexadecimal integer with an absolute value less than 8000 (32768 decimal). 


# 


The current address. 
Example: 


This example illustrates usage of each format of the LDEF directive. 


LINKER BOUND Loads the Linker and designates BOUND as the 
bound unit name. 

LINK A 

LINK B,C 

MAP 

LDEF SYM,X’1234, SYM assigned relative location 1234 


OVLY FIRST ‘Designates end of root and names first nonfloatable 
| overlay 


: | . Rs : 6/78 
LINKER | 2200 © . CB21A 


a“ 
a 


LDEF/LIB 
LINK R 
MAP 
7 LDEF QUIZ,=C QUIZ assigned base location of the previously linked 
q | object unit named C.O. 
OVLY SECOND 
LINKN D 
LINK F 
MAP 
LDEF NEW,SYM NEW assigned same location as the symbol SYM, 
which was defined in the root; i.e., NEW is assigned 
relative location 1234. 
OVLY NEXT 
BASE X’1300’ 
LINK W,X 
MAP | 
LDEF ANY,$ ANY assigned next location after highest address of 
the previously linked nonfloatable overlay, SECOND. 
OVLY THIRD | 
LINK Z 
LINK Q 
MAP 
LDEF FIND,% FIND assigned next location after highest address of 
the root or any previously linked nonfloatable 
overlay. (A previous nonfloatable overlay was named 
SECOND; if it ended at location 1566 and this is the 
highest address ever reached during. the linking of 
object units constituting this bound unit, FIND 
would be assigned location 1567.) 
QUIT 
LIB Directive 


The LIB directive designates a directory as the secondary directory. This directory 
permits the linking of object units that are in a directory other than the primary directory. 
If an object unit specified in the LINK, LINKN or LINKO directive cannot be found in the 
primary directory, the Linker then searches the secondary directory. 

If LIB is not specified, there is no secondary directory; the Linker searches only the 
primary directory. 

The specified secondary directory remains in effect until the LIB directive is respecified 
with a different directory name, or without any directory name. 


NOTE: The LIB directive must be specified before the first LINK, LINKN or LINKO 
directive that requests the linking of an object unit that is in the secondary 
directory. This directive may not be embedded in source code (CTRL). 


FORMAT: 
LIB [path] 
ARGUMENT DESCRIPTION: 
[path] 
Pathname of the directory being designated as the secondary directory. A simple, 


( - relative, or absolute pathname may be specified. (Methods of specifying pathnames are 
described in Section 1.) If path is omitted, no search of a secondary directory is made. 
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LIB/LIB(2, 3, or 4) 
Example 1: 


LIB DIR>SECND 


This directive designates that DIR>SECND > is the relative pathname of the comes 
directory. 


Example 2: 


This example illustrates usage of a secondary directory that contains object units W.O, Y.O, 
and Z.O. | 


LIB DIR>SECND Designates that DIR>SECND is the relative pathname 


of the secondary directory. 
LINK B Requests the linking of object unit B.O; B.O resides 
| in the primary directory. 
LINK A Requests the linking of object unit A.O; A.O resides 
in the primary directory. | 
LINK W Requests the linking of object unit W. O: W.O resides 


in the secondary directory. DIR>SECND>W.O is the 
full pathname of W.O, as expanded by the Linker. 


All specified object units in the primary directory are linked first; then all specified object 
units in the secondary directory are linked, and so on. To cause object units to be linked in 
a specific order, the LINKN or LINKO directive must be used. 


2 
LIB 3 Directive 
4 


The LIB (2, 3, or 4) directive designates directories as the third, fourth or fifth directory. 
If an object unit specified in the Linker directive cannot be found in the primary or 
secondary directory, then the third directory is searched and so on. 

The specified directories remain in effect until another LIB (2, 3 or 4) statement is given. 


NOTE: The LIB (2, 3 or 4) directive must be specified before the first LINK, LINKN or 
LINKO directive that requests the linking of an object unit that is in one of these 
directories, 


FORMAT: 


2 
LIB 3 [| Apath ] 
4 


ARGUMENT DESCRIPTION: 


path 
Pathname of the third, fourth or fifth directory to be searched (if LIB is specified) if 
the object unit specified in a Linker directive is not found in the preceding directories. 
A simple, relative or absolute pathname may be specified. If path is omitted, the 
specified directory (2, 3, or 4) is removed from the list of directories to be searched by 
the Linker. 
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LINK 
LINK Directive 

The LINK directive specifies that the Linker link one or more specified object units. Each 
specified object unit name is put into the link request list. The object units are linked when 
the first subsequent directive other than LINK or START js encountered. When this occurs, 
the Linker searches the primary directory and links the specified object units in the order in 
which they were requested. If all of the object units are not found and there is a secondary 
directory, the Linker searches the secondary directory and links specified object units, in 
the order in which they were requested. If there is a copy of an object unit in both the 
primary and secondary directory, the copy in the primary directory ts linked. 

The order in which object units are linked is important for the following reasons: (1) it 
determines which object units will be in memory simultaneously and which object units will 
overlay other object units and (2) within the root and each overlay, the first start address 
encountered by the Linker (either in an END statement or a START directive) is used as the 
start address for that root or overlay. 

During each execution of the Linker, at least one LINK, LINEN or LINKO directive must 
be entered for each root or overlay. Multiple LINK directives can be specified within a single 
root or overlay. If LINK and/or LINKN and/or LINKO directives request that the same 
object unit be linked more than once within a single bound unit, only the first request is 
honored. | 

LINK directives can be embedded in assembly language CTRL statements; the specified 
object unit(s) are added to the link request list immediately following the object unit in 
which they were embedded. See “LINKN Directive” and “LINKO Directive” for the order 
in which object units are linked if there are embedded LINK directives and/or LINKN 
and/or LINKO directives. 


FORMAT: 
LINK obj-unit, [,obj-unit, }... 


ARGUMENT DESCRIPTION: 


object-unitp 
Name of an object unit to be linked. An object unit name consists of one to six 
characters, each of which must be an alphanumeric character or a dollar sign ($), a 
period (.), or an underbar (_). If multiple object units are specified, they are linked in 
the order convenient to the Linker. The first character must be a letter or dollar sign 


($). 
Example 1: 


LINK FIRST 


This directive causes the Linker to link the object unit named FIRST.O. The primary 
directory is searched first; if FIRST.O is not found, the secondary directory, if any, is 
searched, 


Example 2: 


LIB SECOND>FILE 
LINK R 
LINK T 


The above LIB directive designates that SECOND>FILE its the pathname of the secondary 
directory. In this example, object unit R.O is in the secondary directory, and object unit 
T.O is in the primary directory. 


The above LINK directives will link T.O before R.O, since T.O is in the primary directory. 
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LINK/LINKN 
Example 3: 


LINK A,B,C,D 


This directive causes the Linker to link the object units named A.O, B.O, C.O, and D.O. If iw 
the primary directory contains B.O, and the secondary directory contains A.O, C.O, and 
D.O, the object units are linked in the following order: 


LINKN Directive 
The LINKN directive causes object units to be linked in the following order: 


1, Object units previously specified in LINK directives, and any object units requested in 
embedded LINK directives. The object units are linked in the order in which they are 
found by the Linker. 

. First (or only) object unit specified in the LINKN directive. 

. Object units specified in LINK and/or LINKN directives that are embedded in the 
object unit linked as a result of step 2 above. 

4. Additional object units, if any, specified in the LINKN directive; the object units are 
linked in the order in which they were specified in LINKN, regardless of whether they 
are in the primary or secondary directory. If an object unit contains an embedded 
directive to link another object unit, the object unit designated in the embedded 
directive is linked after the object unit that contains the embedded directive. 

If directives designate that an object unit be linked more than once within a single bound 

unit, only the first request is honored, unless intervening directives are specified that result 

in the first linked object unit being overlays with other code at execution time. 

During each execution of the Linker, at least one LINKN, LINK or LINKO directive must 

be specified for each root or overlay. 

Multiple LINKN directives can be specified within a single root or overlay. 

LINKN directives can be embedded in assembly language CTRL statements; the specified 

object unit(s) are added to the link request list immediately following the object unit in 

which they were embedded. 


WN 


FORMAT: 
letgaie Sbunien Lob eunite |e. 
ARGUMENT DESCRIPTION: 
obj-unity 


Name of an object unit to be linked. An object unit name must be one to six 
alphanumeric characters and must not include a suffix; the first character must be a 
letter or dollar sign ($). The Linker appends the suffix .O to each object unit name, 
and searches for the specified object unit name, including the suffix. 


Example |: 
LINKN X,W 
This directive designates that the Linker link the object unit named X.O and then link the | 
object unit named W.O. Cow 
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MAP/MAPU 


If there are external references in both P-relative and 
immediate memory address forms to an undefined 
symbol, the symbol is listed twice under UNDEF. 


Figure 2-2 illustrates the formats of maps generated by the MAP and MAPU directives. In 
a single-word (SAF) system, each address or value is specified in four hexadecimal digits; in 
a double-word (LAF) system, each address or value is specified in eight hexadecimal digits. 


NOTE: The date and time at which the bound unit was created is automatically put in 
the bound unit’s attribute section. 


* * bound unit name LINK MAP yyyy/mm/dd hhmm:ss.s 


* * START address 
* * LOW address 
* * HIGH address 
[**$COMM address] 

* * CURRENT address 


* * EXT DEFS 

p ZHCOMM® 
p ZHREL® 

* * — ROOT 


[P}* object unit name 


Ba symbol name? 


e 


[P]* object unit name 


[|i] symbol] name? 


* * overlay name 


[P]* object unit name 


Bie symbol name? 


[P]* object unit name 


fp} symbo] name? 


0000 [0000] 

0000 (0000] 

base address of root 

base address of object unit 


Cc 


address~ or value 


base address of object unit 


address© or value 


base address of overlay 


base address of object unit 


é | 
address or value 


base address of object unit 


address° or value 


OMITTED IF MAPU SPECIFIED 


| [* * COMMON common definitions are separated on the map as well as in the cl 


unit when -R is specified 


* * UNDEF 


Figure 2-2. Link Map Formats 
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MAP/MAPU/OVLY 


[P]* object unit name’ base address of object unit 


| symbol name? address of most recent reference’ | 


(P]* object unit name" base address of object unit 


| symbo1 name? address of most recent reference’ | 


e e 
e ° 


P - Protected symbol 
M - Multiply defined symbol 


C - Symbol defines labeled or unlabeled common 


°7HCOMM and ZHREL are reserved symbol names; they appear on every map as protected symbols. 
ZHCOMM is located at unrelocatable zero. ZHREL is located at relocatable zero. When 
ZHCOMM is used in an LDEF directive, the new symbol will not have the attribute of being 
non-relocatable. 


OThe map contains the names of all external symbols currently defined in the symbol table. 
If there are external references in both P-relative and immediate memory address forms to 
an undefined symbol, the symbol is listed twice under UNDEF. Each map line contains up to 
four (SAF) or three (LAF) external symbols. 


“To find a location definition, add the relocation factor at load time to the address shown 
on the map. 


dna] objects units linked are listed under UNDEF, even if they contain no unresolved references. 


“Within the root or a single overlay, the latest reference to an undefined symbol need not be 
in the object unit that contained the first reference to the symbol. For each undefined 
symbol, the following information is given under UNDEF: name of the first object unit that 
contains a reference to the designated symbol, and the relative address of the most recent 
reference. 


Figure 2-2 (cont.) Link Map Formats 


Figure 2-3 presents sample link maps. 


OVLY Directive | | 

The OVLY directive assigns the specified name and a number of the nonfloatable overlay 
that immediately follows, and designates the end of the preceding root or overlay. 

OVLY must be specified as the first directive of each nonfloatable overlay. 

The Linker assigns a two-digit number to each overlay. Overlays are numbered 
sequentially, in ascending order; the first overlay is 00. 


FORMAT: 


OVLY name 
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ARGUMENT DESCRIPTION: 


value-definition 
The external symbol associated with a particular value. 
EXAMPLE ILLUSTRATING USAGE OF THE LINKER 
LINKER TEST -COUT >SPD>LPT0O The bound unit will be a relative file named 


TEST created in the working directory. Link 
maps will be printed on the printer configured 


as LPTOO. 

START LOC 

IST INITST Defines the beginning of initialization code. 

LINK OBJ1 | Requests that OBJ1.0 be linked. 

LIB *DSK0O3 Names secondary directory. 

LINK OBJ2 Requests that OBJ2.0 be linked. 

OVLY ABLE Causes OBJ1.0 and OBJ2.0 to be linked, 
designates the end of the root, and specifies 
that a nonfloatable overlay named ABLE 
immediately follows. The Linker assigns the 
number 00 to this overlay. 

LINKN OBJ3 

LINKN OBJ4 

PROT =OBJ3 Protects the symbol OBJ3. This symbol is 
protected because a subsequent overlay may 
be loaded starting at the base address of 
OBJ3.0. 

MAP Requests a link map. 

OVLY BAKER Designates the beginning of the nonfloatable 
overlay named BAKER. The Linker assigns 
the number 01 to this overlay. 

LINKN OBJ5 

LINKN OBJ6 

PROT =OBJ5 Protects the symbol OBJ5. 

MAP 

OVLY DOG Designates the beginning of the nonfloatable 
overlay named DOG. The Linker assigns the 
number Q2 to this overlay. 

BASE =OBJ5 The overlay named DOG will be loaded 
starting at the address where overlay BAKER 
began. 

LINK OBJ7 

MAP 

OVLY FOX Designates the beginning of the nonfloatable 

| overlay named FOX. The Linker assigns the 
number 03 to this overlay. 

BASE =OBJ3 FOX will be loaded at starting address of 
overlay ABLE, 

IN *DSKOI>MYFILE Designates that the primary directory now is 


the directory named “DSKO1>MYFILE. 
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LIB *DSK02>MYLIB Designates that the new secondary directory 
| is named ~DSKO2>MYLIB; if necessary, this 
directory will be searched after the primary 


directory. 
LINK OBJA 
LINK OBJB 
MAP 


OVLY X-RAY : A nonfloatable overlay named X-RAY 
| - immediately follows. The Linker assigns the 
number 04 to this overlay. 
BASEA=OBJ5 : X-RAY will be loaded starting at the 
beginning address of BAKER. 


LINK OBJC 

MAP 

FLOVLY FLOAT Designates that a floatable overlay named 
FLOAT immediately follows. The Linker 
assigns the number 05 to this overlay. 

LINK OBJE 

MAP 

QUIT 


PROGRAMMING CONSIDERATIONS 


1. While processing object units, the Linker creates a work file LNKWRK.W in the 
working directory. This file is a variable sequential file. It is initially allocated with four 
control intervals of 256 bytes each, but it can be expanded to the amount of space 
available in the working directory. If the bound unit is large, link execution time may 
be reduced by the use of preallocated files. 

2. If the relative output file is preallocated, it must have the same name as that specified 
in the name argument of the LINKER command, it must be a fixed, relative file, and it 
must have a record size of 256 bytes. 

3. If multiple object units contain labeled and unlabeled common, the object units will be 
linked with common blocks appearing in the following order (-R is not specified): 

a. Labeled or unlabeled common (defined in first object unit linked) 
b. First object unit (including external references and definitions) 

c. Labeled common (defined in second object unit linked) 

d. Second object unit (including external references and definitions) 
e. Object unit n 

4. A root or any overlay may reference any symbol defined in any other root or overlay 
including “common” symbol definitions. A common area cannot, however, be 
initialized in any overlay other than the one in which it initially occurs Gs made known 
to the Linker). That is, a common area defined in a root or an overlay can be initialized 
only in the root or overlay in which it is defined. 

5. Relocation can occur during one or both of the following procedures: 

a. Assembly; by specifying an ORG statement, subsequent object text within the 
object unit is relocated. (See the Assembly Language Reference manual.) 

b. Linking; by specifying the BASE directive, subsequent object units to be linked 
within the root or overlay have a specified relative load address. (See “BASE 
Directive”’ earlier in this section.) 
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-POOL id 
id is a two-character ASCII identifier and is the name of the memory pool from 
which all memory required by the spawned task group is to be taken. If specified, id 
must have been defined at system building time. If not, the issuing task group’s 
memory pool is used. 


-ARG arg arg... . arg 
Indicates that additional arguments required by the spawned task group during 
execution follow. These additional arguments are passed to the lead task of the 
spawned group to be used as necessary, and are substituted for parameters in the 
command-in file. If used, the -ARG control argument must appear last. Refer to the 
Commands manual for an explanation of the use of additional arguments. 


NOTE: In any invocation of the SG command, -EFN or ECL, but not both, can be 


specified. If neither is specified, -ECL is assumed and the in_ path argument 
is required. 
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Using the Login Command 

The login command is used to gain access to the system. The login command is entered 
from any terminal not designated as a direct-login terminal or an abbreviated-login terminal. 
(To determine the type of terminal he is at, the user should contact the installation 
supervisor.) The login command causes a task group associated with the user’s terminal to be 
spawned. Once he has access to the system, the user cannot again invoke login unless he first 
issues the BYE command or the task group is otherwise terminated. 3 


FORMAT 
L [login id] [destination id] [etl arg] 
ARGUMENT DESCRIPTION: 


- login id: — | ete. 4 
Establishes the identity of the user who is attempting to gain access to the system. 
Provides the user identification for the spawned task group. The login _id argument 
consists of from one to three fields having the following meanings: 


person 
person.account 


person.account.mode 


person Name of person who may access system; can be from | 
through 12 characters. (For example, WDSMITH could be 
the value for the person field.) 


account Name of an account under which the user is to work; can 
be from 1 through 12 characters. (For example, 
JSINVENTORY could be used as the value for the account 
field.) 


mode Provides a further identification of the user; can be from 1 
through 3 characters. (For example, VER could be used as 
the value for this field.) 
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[destination_id] 

Optional argument that permits the user to login as a secondary user of an existing task 
group. (It is necessary that the running task group have previously issued a request for a 
secondary user terminal; the request for a secondary user terminal is entered by means of 
a Request Terminal macro vall; see the GCOS6 System Service Macro Calls manual for the 
format of the Request Terminal macro call.) To login as a secondary user of a 
user-created applications program, the user enters the value nn, where nn is the task group 
id of the task group in which the application is running. To login as a secondary user of 
task group $T (Terminal Concentrator), see the Terminal Concentration Facility User’s 
Guide. When destination—id is specified, no control arguments can be selected. If the 
secondary login capability is not desired, then destination _id is omitted. 


ctl_ arg 
One or more of the following control arguments can be selected: 
= path ae 
-PO * id. 
Used to override the default lead task and group id/pool id specifications for the task 
group spawned as a result of this login procedure. 


path 
Pathname of the bound unit to be executed as the lead task of the spawned task 
group. If this argument is omitted, the lead task is the command processor. 

id 
Group id/pool id of the spawned task. The group id and the pool id are represented 
by the same 2-character value. If this argument is not specified, the group id is a 
2-character value whose left (first) character was specified when the Listner 
component was activated (the Listner is described in the Operator’s Guide) and 
whose right (second) character is the next unused character in the sequence 0 
through 9 and A through Z, as selected by the system. 
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-HD path 
Used to override the default working directory specification for the task group 
spawned as a result of the login procedure. 


path 
Pathname of the working directory for the soauned task group. If this argument 
is omitted, the working directory pathname is null. 


-LRN n 
Used to override the default maximum logical resource number (LRN) value for the 
task group spawned as a result of this login Procedure: 


n 
Maximum LRN value to be used for the spawned task group. (The maximum 
possible LRN value is 252.) If this argument is omitted, the maximum LRN value 
is the highest value in the system group. 


-LFNn . 
Used to override the default logical file number (LFN) value for the task group 
spawned as a result of the login procedure. 


a | 
Maximum LFN value to be used for the spawned task group. (The maximum 
possible LFN value is 255.) If this argument is omitted, the maximum LEN value 
is 15. 


-ARG arg arg... arg 
Passes additional arguments to the task group spawned as a result of this login 
procedure. These additional arguments are passed to the spawned task in an 
extension of the task request block, and are substituted for parameters in the 
command input file. If used, the -ARG control arguments must appear last. Refer to 
the Commands manual for an explanation of the use of the additional arguments. 


The arguments will be substituted in the following manner: 


o Argument | will always be null 

o If the lead task is the command processor, argument 2 will be the pathname of the 
user-in file (i.e., >SPD>terminal) and arguments 3 through n will be the arguments 
following -ARG. 

o If the lead task is not the command processor, arguments 2 through n will be those 
arguments following -ARG. 
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SECTION 5 
DEBUGGING PROGRAMS 


While a program is executing, it can be monitored by using Debug. If there is not enough 
room in memory for Debug, you can monitor a program by temporarily leaving space in the 
program or by using Patch to append monitor points. (See ‘“‘Debugging Programs Without 
Using Debug”’ later in this section.) 


DEBUG 


Debug provides patching and testing facilities for application programs running under the 
operating system. Debug runs as its own task group. 

Program testing and error correction is performed as an interactive dialogue between the 
operator and Debug. Execution of Debug is controlled by directives entered to Debug. 
Addresses used with Debug are system-wide absolute memory addresses; therefore, Debug 
directives are effective across task and task group boundaries. Debug directives are entered 
through the device specified as user-in in the request to establish the Debug task group (.e., 
a user-specified terminal). 

The following functions can be performed using Debug: 


o Define, store, and execute a sequence of directives either entered through the input 
device, or referenced when a breakpoint directive or trace trap (BRK _ generic 
instruction) is encountered in the load unit being tested.! 

o Set or clear breakpoints in task code to monitor task status. (Breakpoints are described 
in detail later in this section.) 

o Set or clear breakpoints in bound units, to gain control of bound units as they are 
loaded. 

o Display, change, and dump either memory or registers; information may be printed on 
a line printer, the operator terminal, or another terminal. 

o Evaluate expressions. 


Debug File Requirements 

Debug directives stored for later execution reside in a preallocated, relative disk file 
DEBUG.WORK (these directives are identified and described in Table 5-2, “Summary of 
Debug Directives, by Function,” later in this section). The file DEBUG.WORK must be in 
the volume major directory of the disk device referenced in the specify file (SF) directive. 
(The SF directive is described later in this section.) 


Loading the Debug Task Group 

Debug requires a minimum memory area or pool of 2000 words in which to execute. Use 
the MEMPOOL directive during initialization to create such a memory pool and to specify 
the pool’s identification (see the Commands manual for details about MEMPOOL). _ 


Example: 


MEMPOOL ,AB,2000 


This MEMPOOL directive creates a nonexclusive memory pool comprising 2000 words that 
can be specified when the Debug task group is loaded into memory. 


1 a . * s : + . . . . . 
Breakpoints and trace traps either cause a specified Debug directive line to be executed, or interrupt execution of the 
task so that its status can be determined. 
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Debug is loaded into the system as the lead task of a dedicated task group named $D. The 
base level number of the Debug task group is treated as a physical level instead of a value 
relative to the configured system, so that Debug may have priority over system tasks. The 
Debug task group must be assigned two priority levels which are not assigned to other tasks 
or task groups. | 

The following examples illustrate methods of loading Debug. Example | illustrates a 
spawn group command. Example 2 illustrates a create group request and an enter group 
request. The following description applies to both examples: 


The Debug task group’s identification is $D, your identification is GALE.TECH, and the 
base priority level of Debug is 7. Debug will use levels 7 and 8. Directives to Debug will be 
entered through the operator terminal, which is identified by its pathname 
>SPD>CONSOLE. The bound unit DEBUGDB will be loaded, if necessary, and execute 
as the task group’s lead task. 


Example 1: 


Loading Debug by a spawn group command. 
SG $D GALE.TECH 7 >SPD>CONSOLE -POOL AB -EFN DEBUGDB 


Example 2: 


Loading Debug by create group request and enter group request commands: 
CG $D 7 -EFN DEBUGDB 
EGR $D GALE.TECH 7 >SPD>CONSOLE -EFN 


NOTE: The operator terminal is controlled by a system software component called 
the operator interface manager (OIM) that provides a standard means by 
which all tasks can communicate with an operator. OIM identifies the 
messages sent to the operator terminal by providing the task group 
identification in the prefix to each message; OIM requires you to identify all 
input by task group. If you are entering Debug directives through the 
operator terminal, it is recommended that you designate Debug as the OIM 
default task group; otherwise, each Debug directive must be preceded by 
A$DA. To designate Debug as the OIM default task group, enter the 
following command at any time prior to entering the first Debug directive: 


ACA: $D: 


Example 3: 


Loading Debug with a directive terminal, not the operator terminal: 
SG $D GALE.TECH 7 >SPD>KSROI1 -EFN DEBUGDB | 


Debug Operation with MMU 

The Debug task group is loaded in ring O, a privileged state, in order to run effectively in 
a protected (MMU) system. The debugger will handle ‘O30F’ traps and continue as described 
below. 

An error message will be displayed if the user tries to access non-virtual memory within 
any debug directive, except the dump memory directive (DP). The debugger will dump as 
much of the requested memory as possible. Once a non-virtual address is accessed, the rest 
of the current line to be printed will be blank filled. The current non-virtual address will be 
advanced to the value that is the next multiple of 1K. This procedure will continue until the 
area to be dumped is exhausted or the end of memory is reached. 
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Debug Directives 

Debug directives consist of only a directive name or a directive name and one or more 
arguments. Within a directive, arguments are separated from each other by one or more 
spaces. Except where specified otherwise, all argument values are entered using hexadecimal 
notation. 

Multiple Debug directives can be entered on a single line. Each directive, except the last, 
must be followed by a semicolon (:). 

Press RETURN at the end of each line (i.e., immediately after the last or only directive). 

Symbols used in Debug directive lines are described in Table 5-1. 


DEBUGGING PROGRAMS 5-2.1 
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MDUMP AND DUMP EDIT 
UTILITY PROGRAMS 


The MDUMP utility program allows a memory dump to be obtained with no requirement 
that system functions be available. Thus, MDUMP may be used when it is not possible or 
practical to use the dump facility of debug. 

To use MDUMP, you need a disk that contains an MDUMP record on sector O, and a file 
(DUMPFILE) to contain the memory dump. Use the create volume command to prepare 
this disk (see “Preparing for MDUMP,” below). 

To dump memory to the disk file, bootstrap the prepared disk as described under 
‘Procedure for Using MDUMP,” below. This causes the MDUMP record to be loaded and 
executed. When MDUMP terminates, an image of memory is contained in DUMPFILE. This 
file can be edited and printed by means of the Dump Edit utility, described later in this 
section. 


MDUMP UTILITY PROGRAM 


Preparing for MDUMP 
Before loading a program for which a memory dump may be required, enter the create 
volume command, as follows: 


FORMAT: 


— — awe si 
CV path )_MD nn 


ARGUMENT DESCRIPTIONS: 


path 
Designates the pathname to the disk volume being prepared for MDUMP. The 
pathname may be >SPD>sympd or >SPD>sympd>volid. If >volid is specified, the 
volume label is checked. The volume must have been previously formatted via a create 
volume command. (This command is described in detail in the Commands manual.) 
The volume can contain other data. 


eee a 
-MD nn 
Writes the MDUMP bootstrap record to the volume specified in the path argument and 
allocates a file (DUMPFILE) large enough to contain nn 4K modules to be dumped. 
The value of nn should be no larger than the number of 4K modules contained in the 
system being used. 


Procedure for Using MDUMP 
Once an executing program encounters a problem or a halt occurs, you can obtain a 
memory dump by taking the following actions: . 


1. Bootstrap MDUMP, which then performs the memory dump to the disk file 


DUMPFILE. 
ae 2. Use the Dump Edit utility program to print all or a portion of the memory dump from 
( the disk volume that contains MDUMP’S output. 
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Procedure For Bootstrapping MDUMP on Non-Model 
23 Series Systems 

To bootstrap the MDUMP bootstrap record into memory, perform the procedure listed 
below, MDUMP then transfers to the disk file DUMPFILE the amount of memory image 
specified in the -MDUMP argument of the create volume command. 


. Mount the disk containing MDUMP on the channel to be used in bootstrapping. 

. Press Stop and CLear. 

. Set the P-register to 0004 , «. 

. Enter in register B1 the initial address of the memory area into which MDUMP is to be 
read. MDUMP requires one sector of the disk device type on which it is stored. The 
initial address of B1 should be greater than 100,, to insure that hardware dedicated 
locations are not overlayed. 

5. Enter in register R1 the channel number of the bootstrap device (i.e., the disk mounted 

in step 1). 

6. Press Load, then Execute. The bootstrap record MDUMP is read into the memory 

location specified in step 4 above, and dumps the amount of memory image that fills 

DUMPFILE. The dump is complete when an end-of-job halt occurs (see Table 6-1). 


& QD bN— 


NOTE: The size of DUMPFILE is limited by the capacity of the storage device. A 
maximum of 120K of memory can be stored on a diskette file. 


Procedure For Running The QLT And/Or Bootstrapping MDUMP On Model 
23 Series 6/20 Systems 


. Press STOP/STEP button. 

. Press MASTER CLEAR button. 

. If QLT, go to Step 5. 

. Set the P register to the first location to transfer the boot prom data. Any value other 

then zero (prefer 0100 hex). 

. Press LOAD button. 

. Press EXECUTE button. 
CP will stop with P register equal to the attial value Bie CA hex. 
B1 register equal to 0100,,, and R1 register equal to 0400,.¢. 

. Change R1 if different boot channel desired. 

. Change B1 if different buffer address desired. 

. Press RUN button. 

. Press EXECUTE button. 
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MDUMP Halts 

No messages are issued during execution of MDUMP. If a halt occurs during execution, 
the contents of the P-register and RO6 register must be displayed to determine the 
significance of the halt, as indicated in Table 6-1. 


DUMP EDIT UTILITY PROGRAM 


Dumps produced by the Dump Edit utility are written to the user output file which must. 
be capable of receiving a 132-character line. 
There are two sources of dumps: 


o Files created by the previous execution of the MDUMP utility. (All or selected portions 
of the file can be dumped.) 

o Main memory. (A dump of main memory allows you to determine the configuration 
under which Dump Edit is executing.) 


Dumps produced by dump edit may be logical (edited format) dumps or physical (image 
format) dumps. Control arguments in the DPEDIT command (described later in this section) 
allow you to suppress either type of dump. If these control arguments are omitted, 
execution of Dump Edit produces a full logical dump followed by a full physical dump. 
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TABLE 6-1. MDUMP HALTS 


Register Contents 
P-register R6 register Condition Operator Action 


003E; 6a | End of job No operator action required. 
For information only. 


OO3E, 6a Disk error Rebootstrap MDUMP. 
(R6 contains the disk status 
| word.) 


#0 
O3nn #0 Trap handler For a description of trap 
error has 
occurred. 


messages, see the “Trap 


Handling” section of the 
Monitor and I/O Service 
Calls manual. 


4 Address relative to the initial address of MDUMP as stored in memory. 


Logical dumps may be produced for any release of MDT Operating System and for any 
release of MOD 400 Operating System. 

Physical dumps may be produced for any properly prepared dump file, regardless of the 
content of the dump file. 

Logical and physical dumps are printed in both hexadecimal and ASCII notation. 
Duplicate lines, if any, are suppressed. Suppressed lines are designated as described 
subsequently under Dump Edit Line Format. 


Dump Edit Line Format 
The format of a Dump Edit line for both logical and physical dumps is as follows: 


Columns Content 


2-6 For LAF: Five hexadecimal digits designating the starting address of the line of 
dump information; the hexadecimal digit in print position 6 is always 0. This 
forces the dump line to agree with the template printed at the heading of each 
page. 

3-6 For SAF: Four hexadecimal digits designating the starting address of the line of 
dump information; the hexadecimal digit in print position 6 is always 0. This 
forces the dump line to agree with the template printed at the heading of each 


page. 
7 Slash (/) 
8-10 Blanks 
11-91 Sixteen consecutive words; each word is represented by four hexadecimal digits 


and is followed by a space. 
92-95 Blanks 
96-127 ASCII representation of the previous group of 16 consecutive words. A byte 
that is not printable is designated by a period (.). 
1-11 Blanks 


12-93 * * * * * * * * KR k * 


94-132 Blanks 


Physical Dumps 

In a physical dump, the leftmost column of data (four hexadecimal digits for SAF; five 
for LAF) designate real memory addresses. When the Memory management Unit (MMU) is 
in use, there may be ranges of invalid virtual addresses (discontinuities) in a physical dump 
from main memory. When an invalid virtual address is encountered, a message within the 
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physical dump contains the invalid virtual address and the next virtual address to be 
attempted. Thus, when the physical dump resumes, the valid virtual address is known and 
the left column -continues to designate real memory addresses as if the discontinuity did not 
exist. 

A physical dump from an external dump file does not display invalid virtual address 
messages, and the left column of addresses is an uninterrupted continuum of physical 
addresses. 

The physical memory dump in Figure 6-1 was produced by Bune Edit in response to the 
command: | 

DPEDIT DMPVOL DUMPFILE -NL -TO X’720’ 


Logical Dumps 

A logical dump may be tailored by selecting (or suppressing) task group information on a 
group identification basis. File system information may also be suppressed. This tailoring is 
obtained by the use of control arguments in the DPEDIT command. 

All addresses in a logical dump are virtual addresses. The leftmost column of data (the 
addresses whose contents are being shown) are always virtual addresses. This applies to 
dumps of disk files as well as to dumps of main memory. For disk files, Dump Edit 
calculates the virtual address in the same way as the Memory Management Unit-would under 
the same conditions. 

The arrangement of information in a logical dump is described below and illustrated in 
Figures 6-2 through 6-4. 


SYSTEM SUMMARY 


o Location and contents of hardware-dedicated main storage 
o System Time of Dump 
o Location and contents of System Control Block (SCB) 
o Hardware Configuration 
- Model number of central processor 
- Presence (or absence) of the Commercial Instruction Processor, the Scientific 
Instruction Processor, and the Memory Management Unit. 
- Value of the real-time clock scan cycle 
- Presence (or absence) of an operator’s terminal 
- High address of virtual memory 
- High address of physical memory 
o Software Configuration 
- Name of operating system 
- Presence (or absence) of the error message library 
- Size of trap save area (TSA) 
- Size of interrupt save area (ISA) 
- Number of indirect request blocks (IRBs) in IRB pool 
- Presence (or absence) of the batch task group 
o Batch Group Data (shown if batch group is present) 
- Virtual address of beginning of background 
- Virtual address of the end of background 
- Rollout status (currently rolled out or not) 
- Number of completed rollout/rollin events 
- Size of background memory given to foreground 
o Memory Pool Data! »?°° 
- Pool identification 
- Starting address of pool 


1 Supplied for each memory 
2 An ‘*X” appears beside a pool name that can cause the batch group to be rolled out. 
3 The pool name for the batch group is BATCH. 
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OE Re ee, gS oe Shee Roe MES eA ee ean nO 0N0N 0000 O09 NONO VO00 &LvO 0000 Adar 0000 £270 9000 PGgzZ 2000 NONU ONDN NOND /0a¢00 
NON ne ee ee er ee a, ree ae i ae aye 0N00 A000 ONON HONDO HON HONG 000 Yo90 0900 0000 O00 TOO 0909 40ND €9G0 0000 09500 
Mee ee ene a ee mee ea eee 8/Ih 0000 G6dh 9000 $346 20ND O00 D000 0009 0000 ONUN NOD HONDO HUD ONOO 0090 /098500 
SON eee Plena eee Ne eee Boe a a eo eR eel ee 0009 0000 0900 0000 LVADN 0090 O00 ANNAD 0009 N0NDO 0900 N000 C000 0000 0000 000 /0¥500 
Spe eri rare eet ey AME nT) feat eel ee Geiger egy rae UNG 9000 0900 9000 3900 $346 09000 0000 0000 0000 0000 0000 oN00 ONO ONDN ZaTo /N6500 
Sn Cee Sone eee re ee ence et etme eee eae oe 0900 0090 000 0000 0N0N NOOO $146 0000 S146 9000 Qgnen NOOK 000 3AEgay OOM N000 408500 
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¥ ¥ * % ¥ ¥ *% ¥ * *¥ * ¥ * ” * ¥ 
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Te RCT ONT Rg ee geen, eo OLN ig CME es es 0900 0000 ONLY NONDO 0000 0040 0006 0000 0000 9000 0000 9000 0520 AON 0000 0000 40200 
can lat © aga ial 0000 9000 0900 1600 0000 00490 0000 0000 0000 0000 2hr2n 0000 00900 H000 0900 000 F200 
a ala a tl i 0000 9000 0000 0000 V00% 0090 0000 0000 nF20 0000 0900 HONDO N00 HONDO YNDN NVOO 102200 
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Eo eR eae bei dia Neda | 0900 0000 009 N000 gt2n 0000 0000 0000 Jn9gn 00NO 2900 QS69/ 2900 $950 0000 Ste /00200 
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MAIN STORAGE UUMP 1978/65/30 0755216.6 VUMPEDIT<0110-05/25/0748 
v i c 3 4 5 6 7 4 9 A B 

HARDWARE DEDICATED LUCATIONS 
000007 QOVU00 FFFF 9000 0000 0400 0000 0000 0000 0000 0900 0000 00UQ 
00010/ 0000 43A5 Ov00 0000 0000 E40D 0004 0000 0000 0177 0000 8360 
00020/ 0000 90v0 0V00 9001 0000 O101 0000 0163 0000 0105 9000 0107 
000307 000vu 0100 Ou00 O10F 0000 9111 0000 0113 0000 0115 0Vu00 V0117 
00040/ 0000 G11D Oud OL1F O00U Utel 0000 G123 6000 0125 0000 O1e7 
000507 0000 01eD Ou0KG UteF 0000 0131 0000 ¥133 0000 0135 Qv00 0157 
00060/ 0000 01430 OVOU 013F 0000 0141 0000 0143 0000 0145 0000 0147 
00070/ 0000 v14P OVOL O14F 0000 0151 0000 0153 0000 0155 0000 0157 
00080/ 0000 0000 0000 0000 0000 YiboA 000U 667B 0000 O3F9 Ou00 4C78 
000907 0000 0000 Ou0U 4DeF OUOU 4EUF 0000 4EEF 0000 4FCF Ou00 SOAF 
OO0A0/ 0000 V0U0 OVvOU 0000 OVOVW 0NLEN 0000 000 0000 vOu0 0V00 V000 

* * * & * * * * x * * * 

00100/ COFFE tAD3 OFO0e BAD3S OF NE BHADS OF De BALS OFO2 BADS OFOE BADS 

SYSTEM TIME OF DUMP 1901/01/01 0007:07.0 

SYSTEM CONTROL bBLUCK 00177 
001L70/ 0000 OFFF 3035 2F30 332+ 3034 31335 0005 FFFC 0000 0000 W004 
001807 0000 0000 O9Re 9000 6565 Vv000 09ND 0000 9523 006433 7edA YOUD 
00190/ 0032 O00U0 OLVOLU VIED 9000 V000 OU0NU 65bi1 Oude FFFF O0Vv66 VO2S 
OOLAO/ Gu00 VOUS OU0U OCACD GOTL FE7F 0000 V000 0000 vOut av0d YOU 
QOLBOS 000u v0O00 4035 2442 FFFE v4a4e 0101 O049 0000 19vE Ov00 0316 
001CU/ 0vO0 SEBS OVUGS SAFF 0002 0000 0000 UVOVDI 00NOG VOVDO OVOU VOVD 
001D0/ 0000 VOLO 0000 0000 8000 0000 0000 0000 0564 2456 FEFF 9000 


CENTRAL PRKOCESSUR MUDELs 4k GR 9X 

COMMERCIAL PRUCESSOR?: NO 

SCIENTIFIC PRUCESSOR: NO 

MEMORY MANAGEMENT UNIT IN USES YES 

TIME (M{LLI-SEC) BETWEEN REAL TIME CLOCK INTERRUPTS: 0032 
OPERATOR’S TEKMINAL? YES 

HIGH PHYSICAL MeEMURY ADDRESS: C7TFEE 

HIGH VIikTUAL MEMURY ADDRESS: 33AFF 


OPERATING SYSTEMS MOL4O0O/L110 

ERRUR MESSAGE LIbRKAKYs YES 

Size UF TrAP SAVE AREA (WURDS): 00608 

SIZE UF IwtkReRUPT SaVe AREA (WORDS): 0025 
NUMBER UF UNUSED INDIKFCT REQUEST BLOCKS: 09053 


BATCH GROUPS YES 

VIRTUAL ADDRESS UF pEbLINNING UF BACKGROUNDS 30000 

VIRTUAL ADDRESS OF THe Et-No UF RACKGKOUND: 33AFF 
CURRENTLY ROLLEV™UUT?: NO 

NUMBER UF CUMPLETEGO RULLTOUIT/SROLL™IN EVENTSs 0001 

MEMUGRY GIVEN [0 FUREGKOUND FRUM BACKGROUND (CWURUS) 3 0000 
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Figure 6-2. Logical Dump: System Summary 
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MAIN STURAGE DUMP 1978/05/30 0753216.6 DUMPEDIT=-0110"05/25/0748 GCUS6 MOV400"L110-057/16/1052 PAGE U002 
U 1 af 3 4 5 6 7 fe) 9 A 8 C ne F 
MEMURY POUL DEFINITIONS MEMURY FOULS STATUS 
PUOL SEAnT END SIZE TUTAL “UNUSED . MAX [MUMTUNUSEDU NUMBER™UF WUMBER 
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Figure 6-4. Logical Dump: Task Group Structures 
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INSTRUCTIUN: VYG01 P™COUNTER: 060A88 I's 3Fee2 Z: sO0vi As O06AR6H kK33 UDO! 
0900.0064 OUOU 1E74 00OU V000 OVOU S5Fee 0Uu01 YVOV1I BV01 VOLO b6AAG YDU0 6AAB YD03 
0v25 vOVO 9425 VO00 7089 VoOUD OVOU VOVO 6A19 vd003 Ov23 YOO0 4450 FFUO OUNU 0000 
0004 0900 OVOX VOVO OVND VOUVDN 000U VO0UD 0000 0000 OuvOW VONVD0 0000 V900 OVOU V000 
voudoyv 090N OLSY9 0000 1925 0006 0000 U9b6 OUBA YOSF Ou IBIF 0000 1862 NVOU YOUN 
5594 VOU OYRO VOEO OVEF VOU0 Ib1F 0000 1662 Vvd0VU3 0151 VOV0 4A7/ 1879 0u3l1 O00ED 
vooe vous Au4C vO00 0003 v151 O0VNS GOLS 0000 SD4K 0005 VOE9 0029 VOV0 0005 00C3 
QUOF FEFEFFE 90005 O00LDC OCUOF vOUB OVOF G0U3 0003 vdvu0 OvOU 1E74 OVOO YVOVD OVOU SFee2 


WURK SPACE bLUCK 30103 

NVEQ vOVU3 3941 4450 4544 4954 0000 O04 0000 1850 O0VU00 0VOVD0 2001 0001 0017 1879 
Ovd00 v000 OVv01 v0S$3 E787 03357 O00U 1879 2001 VO3A E787 Vill O0V0O 1879 2u01 YOSE 
E787 vest OUNO 14679 0001 0045 £787 O1A5 0000 1879 OV00 00600 9001 2001 00035 3953 
0005 VIicA 0003 v103 0005 VISA N000 0000 0000 v900 0097 2041 4450 4544 4954 2D350 
3134 5020 3035 2F50 352F 3059 3132 GOVE 4144 554D S020 4354F 4050 4C45 5445 0015 


ucou o—53 OFCU 0100 FFCU “OFC CBCU 0015 0001 vAUO 1981 1510 2C01 0001 OADL 1981 - 


1514 ¢C€51 Ovu01 VAO1 1981 1513 CCOF OO0V1 0401 1981 150E OF 89 300F 0901 OF 36 BDFS 
CeCo 1510 CFS VOUS CBCU FFC6 7001 E844 FFFF v001 0603 CHCO 1465 0001 1404 AB/0 
eve AF4O 145 9BCO FFBE ABCO 145e¢ ICFB F&71 FF/72 17FkE 93C0 OV7A 93L0 OLSU 82C0 
FroF vOU4 0587 9CHO 0000 0018 CCCI vdel 0F88 9CCO 0253 8DV1 0901 OOA2 95CO VIFI 
CFCO QOAE CFCO OEAF CKBU VNL0 0000 CFCO OEAC V0V1 0506 CBCO 14186 5SC14 0001 0504 
9300 14¢8 95CQ 0D49 B2CU FFYA 0001 0515 93CO0 vebO 95C0 Veale 95CO YVetEC 95CU 0054 
93Cu uDo7 95CU ODSC BeCo FFEA 0040 0503 93C0 0D68 95CU 03S6A B82CU FFK2 0002 0503 
95CV VNCA B8S5C0 14AE 0000 0000 0000 V0U0 0000 0000 0000 0000 0000 0000 0000 0000 
N000 0000 900N 0900 000U 0N00 0000 0000 0000 v000 0000 v000 0000 G000 0000 V000 
* s k * * * * * x * * k ni * * * 
0u00 vO0O OV0V 0000 0000 0000 9FCU 0041: KCCO 0048 9875 1001 0381 0032 ItFF ECC3 
0U0e v&76 2L00 F0AG TL2b 090D ABCO U1E2 AFCO 01D4 FuAO F7EE S3EFF S$9FD 1EFF 1909 
BACO. 00c9 9F 40 0052 OF 86 9840 OU2F 1983 85C8 OO1F AB4YO OOIF ACEF ECUS AF4O 0018 
93C0 0028 3901 0008 BBCU FFUS 9355 BCL6 B84CO 001C OFEB 9870 2507 OFH1 143A 9870 
2512 OFFC 9870 2503 OFFI 9870 2502 OFF6 0003 0160 0003 0000 0000 0002 7FFF 0002 
7FFR vous 9009 0000 16CA 0000 0005 VOCA 0003 9FCO 0028 F872 BECO FFFO AF4U FFFI 
YbCv o0e7 OFRS Y9CCO 0020 BB/1 9853 1041 BED1 1£01 Cb91 CFCO 00148 39u0D B957 0902 
OFFS 1CV0 eCN0 CODD DOEE C955 O9ED &8v3 3904 OFFA 8755 OF 8S ABCB VOUT BB4e FFFF 
A3CK VOU! 0003 0232 00035 YVeYC 0000 VNVN 0006 2D4E 4FSF 4C4F 4749 4341 4C20 OI9A 


Figure 6-4 (cont). Logical Dump: Task Group Structures 
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- End address of pool 
- Total size of pool 
- Total available space 
- Maximum contiguous available space 
- Number of available fragments (pieces) of pool space 
Number of users 
O Susteni Symbol Table 
The names and values of all symbols that have an entry in the system symbol table are 
displayed. Symbols are grouped according to the bound unit(s) in which they occur. 


File System Structures 
The logical dump displays the location aad content of the following file system 
structures: 


o Volume Descriptor Blocks (VDBs) 
o Directory Descriptor Blocks (DDBs) 
o File Descriptor Blocks (FDBs) 

o Buffer Control Blocks (BCBs) 


The hierarchy of these structures is indicated by the dump as shown in Figure 6-2, which 
is an abridged section of a logical dump. Each block is assigned an integer that corresponds 
to the level of the block in the hierarchy. The headings of all blocks are indented according 
to the depth of the block. This makes it easy to see which files belong to volume major 
directories and which belong to subordinate directories. 

The display of the tree of file system structures may be suppressed at run-time. 


TASK GROUP STRUCTURES 


The logical dump displays the location and content of the following structures as shown 
by Figure 6-3, which is an abridged section of a logical dump. 


Group Control Blocks (GCBs) 

Task Control Blocks (TCBs) for each GCB 

Indirect Request Blocks (IRBs) for each TCB 
Request Blocks (Group, Task, or I/O) for each IRB 
Trap Save Areas (TSAs) for each TCB 

File Control Blocks (FCBs) for each GCB 

Work Space Blocks for each GCB 


0o0o00 00 0 


At run-time, the task group structures for any designated task group may be displayed or 
the display may be suppressed. 

For the system task group, IRBs (and hence also RBs) are displayed only when the file 
being processed is an external dump file; i.e., the display is suppressed when the input is 
from current main memory. 

Work space blocks and FCBs for the batch task group are not displayed when the batch 
group is rolled out. 

The display of structures for each task group is preceas ‘by a header containing the task 
group identification. 

Where appropriate, the header for the task control block (TCB) contains a bound unit 
name. 

The header for each file control block (FCB) also contains the logical file number (LFN) 
of the file. 

Work space blocks may also be labelled as FCBs, TCBs, or RBs if they appear as these 
structures within the same task group. 

The firmware-defined fields (instruction, P-counter, I’, Z, A, R3, and B3) for each trap 
save area (TSA) are displayed. If the instruction is a monitor call, the function code is also 
displayed. 
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Headings for task group structures are indented to show the hierarchical relationship. 

For non-system task groups, the display of the group control block (GCB) is extended to 
show the group’s logical file table (LFT) and the logical resource table (LRT). The LFT and. 
LRT begin at the end of the GCB. 

In addition, a possible context of the remaining data and address registers (R1, R2, R4, 
R5, R6, R7, Bl, B2, B4, B5, B6, and B7) is displayed for each trap save area. This context, 
which is extracted from the work space area of the trap save area, may not be valid in all 
cases, but, in general, is correct due to internal conventions of the MOD 400 Operating 
System. 


DPEDIT Command 

The DPEDIT command loads the Dump Edit utility program. mediately after Dump 
Edit begins executing, a message is issued to the error output file giving the unique version 
number in the following format: DPEDIT-nnnn-mm/dd/hhmm. The message ‘SDUMP 
COMPLETE?” is issued to the error-out file immediately before the execution of Dump Edit 
terminates. 


FORMAT: 
DPEDIT [path] [ctl_arg] 


ARGUMENT DESCRIPTIONS: 


path! | 
Pathname of the memory dump file to be printed. 
ctl_ arg 
Control arguments; zero, one, or more of the following control arguments may be 
entered, in any order: 
eg catia 
-NL 
No logical dump of system control structures praeuces: 
Default: Logical dump produced. 
ens 
-NP 
No physical dump of memory produced. 
Default: Physical dump produced. 
: -FROM et 
FM X’address’ 
Low-memory address (up to four hexadecimal digits for SAF and five for LAF) of 
area that will appear in physical dump; must be specified 1 in hexadecimal. This must 
be a real (not a virtual) address. 
Default: Absolute 0. 
_ -TO X’address’ 
High-memory address ae to four hexadecimal digits for SAF and five for LAF) of 
area that will appear in physical dump; must be specified in hexadecimal. This must 
be a real (not a virtual) address. — 
Default: High memory address of the dump file. 
. oe 
MEM 
~ Produces a dump of main memory. If both the hati argument and this arsument are 
specified, the Daw argument is ignored. 


1 Fither the path argument o or the -MEMORY control argument must be specified. 
If the -FROM control argument is used in conjunction with the -MEMORY control argument, then the address that is 
specified must be a main memory location whose virtual address is the same value as its real address. 
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Default: A dump is produced of the file specified in the path argument. 


oo 
-GP 
Requests the logical dump to contain task group-related information for the 
specified group(s) only. 
Default: Task group information for all groups is included in the logical dump. 


\ group id [ group-id]... 


NOTE: Either the path argument or the -MEMORY control argument must be specified. 
Example 1: | 
DPEDIT * DMPVOL>DUMPFILE -NL -TO X’3000’ 


This command loads the Dump Edit utility program and requests only a physical dump of 
the first 12K locations of the specified dump file. 


Example 2: 
DPEDIT -MEM 


This command loads the Dump Edit utility program and Fequests a logical and physical 
dump of current main memory. 


Example 3: 
DPEDIT -MEM -GROUP $S $D -NP -NF 


This command loads the Dump Edit utility program and requests a logical dump of only the 
System and Debugger groups from current main storage. This command suppresses display 
of the file management structures. 


Example 4: 
DPEDIT * DUMPER>DUMP256K 


By specifying a group that does not exist, (i.e., XX) this command requests an abbreviated 
logical dump consisting of only the System Summary from within the specified dump file. 


Operating Procedure for Dump Edit 
The following steps must be performed before the Dump Edit program can be executed. 


1. Mount the disk volume containing Dump Edit. 

2.1f Dump Edit is being used to print MDUMP output, mount the disk volume that 
contains the memory image obtained from the MDUMP memory dump. 

3. Execute Dump Edit by specifying the DPEDIT command described previously. 


DPEDIT processing can be stopped at any time by depressing the “BREAK” key. A 
“** BREAK**”" message appears on the user’s terminal when the processing stops. GCOS 6 
command may be specified at this point. If the program interrupt command (PI) or the 
unwind command (UW) is specified, the end-of-processing details are automatically handled 
and control returns to the command processor with a successful subtask completion status. 
If the start command (SR) is specified, DPEDIT resumes processing. 

When Dump Edit is used to print MDUMP output, the address mode that was in effect for 
MDUMP must be used for Dump Edit; ie., the SAF version of DPEDIT processes SAF 
memory dumps; and the LAF version processes LAF memory dumps. 
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Messages 

Fatal errors terminate DPEDIT processing, return control to the command processor, and 
post an unsuccessful subtask completion status. Fatal errors include logical I/O errors and 
physical I/O errors as well as DPEDIT-specific errors. Fatal error messages are written to the 
ERROR_ OUT file by the system service, Error Handler, and are described in the System | 
Messages manual. For convenience, fatal error messages that are specific to DPEDIT are ee 
summarized in Table 6-2. 


TABLE 6-2. DPEDIT — SPECIFIC FATAL ERROR MESSAGES 


Information . | Meaning 
2502 ILLEGAL NUMBER OF ARGUMENTS. | — The number of arguments specified in the DPEDIT 
command is excessive. 
~ 2503 NON-NUMERIC CHARACTER IN A non-numeric character was found in a DPEDIT 
NUMERIC ARGUMENT | argument where a numeric argument is required. 
2507 ARGUMENT NOT RECOGNIZED An argument has been specified in the DPEDIT 


command which does not conform to the 
defined list of control arguments. 
2512 REQUIRED ARGUMENT MISSING In certain situations a DPEDIT ne may be 
| _ 4 : required. If such a situation occurs and the argu- 
ment is missing, this message is produced. 


2513 ADDRESS MODE INCOMPATIBILITY The address mode (SAF or LAF) of the dump file 
differs from that of the executing DPEDIT utility. 
2514 DUMP FILE IS INCORRECT | The dump file must be a BES-200 Relative file 
FILE-TYPE ' with no deletable records created by the CREATE_ 
| | | — VOL (CV) utility. 
2515 DUMP FILE IS INCOMPLETE | The dump file, when filled by MDUMP, did not 


attain a successful end-of-job condition (see 
Table 6-1). The dump file is therefore incomplete. 


Immediately after execution of DPEDIT begins and immediately before execution 
_ terminates, a message is written to the ERROR OUT file. These ae are explained in 
the description of the DPEDIT command. 

Informational messages that generally reflect some condition peculiar to the data within 
the dump file may be interspersed with the dump information in the USER OUT file. 
These messages are designed to facilitate analysis of the dump and are listed below in 
alphabetical order. A brief explanation of each message is included. 


ADDRESS POINTER IS INVALID 
A virtual address contained in the dump file is invalid. 
BATCH GROUP IS ROLLED OUT | | 
The background was rolled out when the memory dump was taken. 
DATA NOT READABLE 
Dump Edit tried to read the contents of a nonexistent location on the dump file, or an 
uncorrectable read error was encountered. If this condition occurs more than five times 
within a given task group, processing is terminated. | 
DUPLICATE FILE CONTROL BLOCK STARTING ADDRESS 
The specified file control block has already been displayed. 
DUPLICATE GROUP CONTROL BLOCK STARTING ADDRESS 
The specified group control block has already been displayed. 
DUPLICATE TASK CONTROL BLOCK STARTING ADDRESS 
The specified task control block has already been displayed. 
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DUPLICATE WORK SPACE BLOCK 
The specified work space block has already been displayed. 

INPUT IS NOT A MOD400 DUMP FILE 
The external dump file to be processed contains a dump of an MDT Operating System. 

INSTRUCTION WHICH TRAPPED IS AN MCL AT LOCATION nnnn. FUNCTION CODE 

IS nnnn. 

This message gives information about the associated trap save area. 

INSTRUCTION: nnnn P_COUNTER"nnon U’:nnnn Z:nnnn A:nnnn R3:nnnn B:3nnnn 
This message gives information about the associated trap save area. 

INVALID WORK SPACE BLOCK POINTER 
A work space block was encountered that does not begin on a 32-word multiple 
boundary. 

LOGICAL DUMP CAN GO NO FURTHER. PHYSICAL DUMP IS SUGGESTED. 
DPEDIT has determined that some operating system structure has been overwritten. 
This message can appear only during a logical dump. 

NO ENTRIES 
System Symbol Table is empty. 

NUMBER OF ALLOCATED WORK SPACE BLOCKS EXCEEDS 60 
More than 60 work space blocks have been allocated for the current group control 
block. 

NUMBER OF BUFFER CONTROL BLOCKS EXCEEDS 25 
More than 25 buffer control blocks have been allocated for the current file descriptor 
block. 

NUMBER OF FILE CONTROL BLOCKS EXCEEDS 40 
More than 40 file control blocks have been allocated for the current group control 
block. 

NUMBER OF GROUP CONTROL BLOCKS EXCEEDS 40 
More than 40 group control blocks have been allocated for the current configuration. 

NUMBER OF INDIRECT REQUEST BLOCKS EXCEEDS 25 .- 

More than 25 indirect request blocks are allocated for the current task control block. 

NUMBER OF TASK GROUP CONTROL BLOCKS EXCEEDS 40 
More than 40 task group control blocks have been allocated for the current group 
control block. 

NUMBER OF TRAP SAVE AREAS EXCEEDS 10 
There are more than 10 trap save areas for the current task control block. 

THIS WORK SPACE BLOCK IS A FILE CONTROL BLOCK 
The specified work space block has appeared previously as a file control block in this 
task group. 

THIS WORK SPACE BLOCK IS A REQUEST BLOCK 
The specified work space block has appeared previously as an I/O-, a task-, or a 
group-request block. | 

THIS WORK SPACE BLOCK IS A TASK CONTROL BLOCK 
The specified work space block has appeared previously as a task control block. 

VIRTUAL ADDRESSING DISCONTINUITY EXISTS AT VIRTUAL ADDRESS hhhh. 

DUMP WILL RESUME AT VIRTUAL ADDRESS kkkk. 

The virtual address, hhhh, is invalid. The physical dump from main memory will 
attempt to restart at virtual address, kkkk. 

VIRTUAL ADDRESSING ERROR... INVALID OFFSET 
A virtual address has been encountered whose offset field exceeds the size field of its 
virtual space segment descriptor. | 

VIRTUAL ADDRESSING ERROR... INVALID SEGMENT 
A virtual address has been encountered whose segment field designates an invalid 
virtual space segment descriptor. 
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APPENDIX A 
INTERPRETING AND USING | 
MEMORY DUMPS 


Memory dumps can be obtained by using Debug or Dump Edit. It is preferable to use 
dumps produced by Dump Edit; they are in edited format and are much easier to interpret 
(see Section 6). | 

This appendix describes significant locations on memory dumps, how to interpret the 
contents of locations on memory dumps, and how to use memory dumps to perform the 
following procedures: 


o Finding the location in memory of your code 
o Determining where a trap occurred 
o Determining the state of execution of your code 


A trap is a special software- or hardware-related condition that may occur during the 
execution of a task. Many traps are caused by an error, but a few, such as the Monitor Call, 
are not. The above procedures may have to be performed if a trap message is issued. Traps 
and trap messages are described in detail in the ““Trap Handling” section of the System 
Services Macro Calls manual. 


NOTE: In this appendix, all references to memory locations and offsets are for both SAF 
and LAF modes (short-address form and long-address form, respectively), and 
offsets always are in hexadecimal. LAF address and offsets are enclosed within 

g parentheses and indicate the two-word form. 


SIGNIFICANT LOCATIONS ON MEMORY DUMPS 


Table A-l describes memory locations on the dump that it may be useful to refer to 
during debugging. It is assumed that you are familiar with the data structures referenced. 
Brief definitions of these data structures are contained in the glossary of the System 
Concepts manual, Figure A-1 illustrates a map of systems data structures. 


TABLE A-1, SIGNIFICANT LOCATIONS ON MEMORY DUMP 


Memory Address Meaning 

0010 (0010/0011) Head of queue of available trap save areas (TSA’s). 

0018 (0018/0019) Pointer to system control block (SCB). This is the key to locating all system 
data structures. 

0020-0023 Level activity flags for levels 0 through 63. Bits ON indicate which levels are 


ready to execute; the lowest of these levels is the level currently executing 
(i.e., the active level). The level 63 bit always is on. The clock level bit (4) 
may be on, and the Debug level bit is on if the dump resulted from a Debug 
DP directive. 


0052-007F Trap vectors. Each trap vector is associated with a specific trap condition and 
(0024-007F ) points to that trap handler’s entry address. The trap vector for trap number 1 
is in location 007F (7E/7F). The trap vectors for subsequent trap numbers 
are in descending, contiguous, locations; i.e., the trap vector for trap number 2 
is in location OO7E (7C/7D). 
doy * 0080-00BF Pointers to interrupt save areas (ISA’s) for levels 0 through 63, respectively. 
( (0080-00FF) A null value means there is no dedicated task (i.e., a driver) or nondedicated 
- task ready to execute on the specified level. 


INTERPRETING AND USING 


MEMORY DUMPS A-l CB21 


SdNWNd AYOWAW 


ONISN GNV ONILAYdaAINI 


ABSOLUTE LOCATION 
1846 (18/19), 


-3.(+6 +7) -2 (-3/-2) | -1(-1) 


es Ryers) 
FCB CHAIN 
: MAX LFN LFNO 
a re ra ae ee POINTER jmaxcen | urNo 


LFT 


| 


GCB (+0 +1) +4442 +3) +4 (4+5/+6) +7 (+B/+C) +8 (+D/+E) 


(-1) LRT (Q/+1) 


RCT 1 


1 (-2/-1) RCT O 


CHANNEL 
(IF DEVICE) 


FIRST TCB 


OF GROUP 
-124-1C 1B) -D (+5/+4)  -C (-13/-14) “A (-10/A) — -9 (-E -D) -8 (-C/-B) -7 (-A/-9) 6 (-8) “1 (-2/-1) —Rkh——_—_—— 
TSA +3 (+4) +6 (+8/+9) 


TCB 
BU) . +5 (+8/4+9) +6 (+A/+B) . SAME LEVEL NEXT TSA IF NEEDED 
IRB +1 (+2) 
BAS 
10RB OK TRB 


NEXT TCB OF GROUP 


Figure A-1. Data Structure Map 


Locations Relative to the System Control Block or Group Control Block 


SCBt+3 (+6) 
Pointer to first group control block (GCB) 
GCB+0 (+0/+1) 
Pointer to next GCB in linked list of GCB’s. 
GCB+1 (+2) | 
Task group identification ($S is the system group; $B is the batch group). The system 
will convert your user identification to non-ASCII representation. 
GCB+8 (+D/+E) | 
Pointer to LFNO of logical file table (LFT). 
GCB+7 (+B/+C) : 
Pointer to LRNO of task group’s logical resource table (LRT). 
GCB+4 (+5/+6) 
Pointer to first task control block (TCB) of the group. 
LRT-1 (-1) 
Number of entries in the LRT. 
LRT+0 (+0/+1) 
Pointer to LRN 0’s resource control table (RCT); the RCT’s for subsequent LRN’s are 


in contiguous, ascending locations (LRT+1 points to LRN 1’s RCT). A null entry 
indicates that the associated LRN is not used. 


NOTE: Within an RCT, location 0 is the channel number of the resource if it 
is an input/output device. 


RCT-1 (-2/-1) 
Pointer to task control block (TCB) for that resource. . 


Locations Relative to the Task Control Block (TCB) Pointer for the Desired Priority Level 


TCB-6 (-8) 
Hardware-assigned priority level of the task. 
TCB-12 (-1C/-1B) 
Pointer to current bound unit BUD. 
TCB-A (-10/-A) 
Pointer to end of queue of requests for the task. 
TCB-9 (-E/-D) 
Pointer to start of queue of requests for the task (e.g., I/O requests for a driver). 
TCB-C (-14/-13) 
Pointer to the group control block (GCB) for the group to which this task belongs. 
TCB-D (-15/-14) 
Link to the queue of this group’s TCB’s. 
TCB-7 (-A/-9) 
Pointer to last TCB on that priority level. 
TCB-8 (-C/-B) | | 
Link to other task control blocks (TCB’s) of the same or different task groups assigned 
to the same level. 
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TCB-1 (-2/-1) | 
Pointer to the queue of trap save areas (TSA’s) for the task. (Trap save areas are 
described in detail in the ““Trap Handling” section of the System Service Macro Calls 
manual.) If a TSA is present, the task is executing system code or a user trap; if no 
TSA is present, check the program counter in the interrupt save area (ISA) portion of 
the TCB to determine the tasks’s progress. 


TCB+0 . 
Device word, including channel number and level number. This entry is null if the task 
does not drive a device. 


TCB+n 
Hardware ISA. 


INTERPRETING THE CONTENTS OF A DPEDIT LOGICAL DUMP 


This section addresses dump interpretation when the DPEDIT dump format is used. 


Finding the Location in Memory of Your Code 

Locate your group-id and the TCB for your bound unit (BU). The first six characters of 
the BU filename are printed beside each TCB of the group. 

The address at TCB-11(-1B/1A) is the start address of the BU. Calculate sintive zero of 
the BU by subtracting the relative start address on its link map from this address. 


Determining the State of Execution of Your Code at the Time of the Dump 

Dump analysis begins with gathering all relevant information: the dump itself, the console 
hard-copy (if any) of the activity of a particular group (or groups), copies of the 
CLM_USER and >START_UP.E files, plus any link maps. 

These materials are required to understand the environment of the system represented in 
the dump. | 

Three conditions are discussed below: 


1. Halt at level 2 
2. User level active at the time of dump 
3. No level active at the time of dump, except level 63. 


Halt at Level 2 

Examination of the level activity indicators at locations 20-23 confirms that level 2 is 
active. The system will force this condition to occur if either TSA or IRB resources are 
exhausted (see CLM SYS directive). Note that once level 2 becomes active,: other lesser 
priority levels may activate but will not receive CPU time and should be ignored. 

The D1 register contains an ASCII IR (4952) when IRB exhaustion has occurred. 
Location 10 (10/11) is zero when TSA exhaustion has occurred. 

If this symptom persists after augmenting the number of TSA/IRBs available to the 
system, it is possible that either your code or the system is improperly altering the TSA/IRB 
chains. To verify this, take a memory dump immediately after system startup. This allows 
easy location of the TSA chains from location 10 (10/11) and the IRB chains from the first 
location of the SCB. Compare this dump to one taken after all TSA/IRBs are supposedly 
exhausted to verify that they really are. If the system is suspect, supply both dumps. to 
Honeywell if you have a maintenance contract. TSAs can also be exhausted by a recursive 
trap. A recursive trap uses up all available TSAs. Adding TSAs simply allows for greater 
recursion. In this. instance, the system is suspect and dumps should be supplied to 
Honeywell. 7 
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User Level Active at the Time of Dump 

This often indicates a halt or software loop condition on the active level. When a level is 
active, the pointer to the TCB associated with the code running is in the interrupt vector for 
that level. Match the TCB pointer with the TCBs listed for the groups present in the system. 
When a level is active, use the P-counter in the ISA portion of the TCB to locate the 
software running at the last time this level’s context was saved. Since the system clock is 
active on level 4, the P-counter in the ISA for this level is usually helpful. It 1s also helpful to 
record the contents of R/B registers and EO when entering STEP mode at the control panel 
prior to taking the dump. 


No Level Active at the Time of Dump, Except for Level 63 

This condition usually indicates a system failure in that all tasks have been suspended and 
none are being reactivated. In this situation it is helpful to determine the conditions existing 
at this time. To do this, examine all TCBs in groups other than $S group. If the TCB under 
examination has not experienced a default trap condition, it may or may not have an 
associated TSA. If a TSA is shown, DPEDIT will display the monitor call function code if 
the trapped instruction is 0001 (monitor call generic). The function may be decoded using 
the numerical listing included in this appendix. 

When the system is called for a monitor function, only those ities: that must be 
preserved by the system are saved in the TSA workspace. The saved registers are: B7, BO, 
BS, B1, R5, R4, M1, beginning at TSA location +9 (+E//F). The trap save area (TSA) is 
illustrated below: 


WORK 


y SPACE fad 


DETERMINING WHERE A TRAP PROCESSED BY THE SYSTEM DEFAULT HANDLER 
OCCURRED IN YOUR CODE 


If a trap message occurs on the operator terminal from the system default trap handler; 
1.e., (id) BUname (0303zz) level, the TCB of the referenced task group may be located using 
the bound unit name (BUname). In this situation, unless the TCB is subsequently 
re-requested, the last two areas associated with the TCB are related to the system handling 
of the trap. The first TSA following the TCB was used by the system to forceably terminate 
the task request in progress when the trap occurred. Your information is found in the next 
TSA associated with the TCB. It contains the hardware information described in the 
previous section of this appendix, followed by a complete set of registers current when the 
trap occurred. The order of the registers, beginning at location +9 (+E/F) of the TSA, is: B7, 

~B6, B5, B4, B2, BI, I, R7, R6, R5, R4, R2, RI, M1 (B3, R3, I are already in the TSA). 
When the TCB has been re-requested, only this second TSA remains attached to the TCB. 
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FINDING THE LOCATION IN MEMORY OF YOUR CODE 


The three activities above may be performed without aid of the DPEDIT logical dump 
presentation. The examination of TCB contents is the same once the TCB is located. Use the 
following procedure to find the TCBs for your group. 


1. Go to location 0018 (18/19); this location contains a pointer to the system control 
block (SCB). 

2. Go to location SCB+3 (+6); this location contains a pointer to the first group control 
block (GCB); the first word links to other GCB’s in the system. Determine the group id 
at GCB+1 (+2/+3). 

3. Go to location GCB+4 (+5/+6) to determine the location of the first task control block 
(TCB) of the task group. 

4. Go to location TCB-12 (-1D/- iC) to determine the location of your current bound unit 

descriptor (BUD). 

5. Go to location BUD+6 (+A/+B). This location is the relocation factor of the bound 
unit; your code should start at this location. 

6. To confirm that your code does start at location BUD+6 (+A/+B), go to location 
BUD+5 (+8/+9); this location points to the location of the bound unit attribute section 
(BAS). 

7. Go to location BAS+O to determine the bound unit’s root name; this name should be 
the same file name (i.e., the same leading six characters) that you specified in the name 
argument of the LINKER command. 

8. If you did not find the root name for which you were looking, go to location TCB-D 
(-16/-15); this location points to the next TCB of the task group. Follow through the 
chain of TCB’s until you find your task’s task control block. 


INTERPRETING THE MONITOR CALL NUMBER ON MEMORY DUMPS 


Table A-2 is ordered numerically to facilitate identification of a monitor call function 
code, and provides a brief description of each Executive monitor call. 
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Monitor 
Call Number 


0100 
0101 
0102 
0103 
0104 
0105 
0106 
0107 
0108 
0200 
0202 
0203 
0204 
0205 
0207 
0208 
0209 
0402 
0403 
0404 
0405 
0406 
0500 
0501 
0502 
0503 
0504 
0505 
0506 
0507 
0508 
0600 
0601 
0602 
0603 
0604 
0700 
0701 
0703 
0705 
0706 
0707 
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Function Description 


Wait for operation complete 
Wait on request list 

Test completion status 
Terminate request start address not modified 
Terminate request $B4 has new start address 
Dequeue IRB 

Post IRB 

Return request block address 
Locate user RCT 

Request I/O transfer 

Disable device 

Reset device attention 

Enable device 

Start error logging 

Exchange error log 

Get error logging information for this device 
End error logging 

Get memory 

Get available memory 

Return memory 

Return partial block of memory 
Status memory pool 
Request clock 
Cancel clock request 

Suspend for interval 

Suspend until time 

External date/time - convert to 
External time - convert to 

Get date/time 

Internal date/time - convert to 
Set system date/time 

Request semaphore 

Cancel semaphore request 
Reserve resource 

Release semaphore 

Define semaphore 

Execute overlay 

Load overlay 

Status overlay 

Reserve area and execute overlay 
Release overlay area 

Release, wait on RB and recall 


TABLE A-2. SUMMARY OF EXECUTIVE MONITOR CALLS 


Macro Call Name 


SWAIT 
$WAITL 
STEST 
STRMRQ 
$TRMRQ 


S$RBADD 


$RQIO 
$DSDV 
$RDVAT 
SENDV 
SELST 
SELEX 
SELCT 
SELEND 
$GMEM 
SGMEM 
$RMEM 
$SRMEM 
SSTMP 
$ROQCL 
$CNCRQ 
$SUSPN 
SSUSPN 
SEXTDT 
SEXTIM 
$GDTM 
SINDTM 


$RQSM 
SCNSRQ 
$RSVSM 
$RLSM 
$DESM 
SOVEXC 
SOVLD 
SOVST 
$OVRSV 
S$OVRSL 
SOVRCL 
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Monitor 


Call Number 


070A 
0700 
0800 
0801 
0802 
0803 
0804 
0805 
0806 
0900 
0901 
OAQOO 
0902 
0903 
OAQO1 
OA02 
0A04 
OBO0 
OBO] 
OBO2 
OCO0 
0CO2 
0CO3 
0C04 
O0COS 
O0C06 
0C08 
ODOO 
OD03 
OD04 
ODO5 
OD07 
OD08 
OD09 
ODOA 
ODOB 
OEOO 
OFOO 
OFO1 
1010 
1015 
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Function Description 


Create overlay area 

Unload overlay 

User input file - read 

User output file - write 

Command infile (ead command-in file) 
Error output file - write to 

New user input file - redefine 

New user output file - redefine 

New command input - reset 

Operator information message - display 
Operator response message - display 
Trap handler connect 

Console message suppression - on 
Console message suppression - off 
Enable user trap 

Disable user trap 

Trap handler query 

Read external switches 

Set external switches 

Clear external switches 

Request task 

Create task; same bound unit as issuing 
Create task; different bound unit than issuing 
Delete task 

Spawn task; same bound unit as issuing 
Spawn task; different bound unit than issuing 
Command line - process synchronously 
Request group 

Create group 

Delete group 

Spawn group 

Abort group request 

Suspend group 

Activate group 

Abort group 

New process 

Request batch execution 

Report error condition 

Report error condition 

Associate file 

Disassociate file 
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TABLE A-2 (CONT). SUMMARY OF EXECUTIVE MONITOR CALLS 


Macro Call Name 


S$CROAT 
SOVUN 
$USIN 
$USOUT 
$CIN 
$EROUT 
$NUIN 
SNUOUT 


$OPMSG 
SOPRSP 
$TRPHD 
$CMSUP 
$CMSUP 
S$ENTRP 
$DSTRP 
$TRPHD 
$RDSW 
$SETSW 
$CLRSW 
$ROTSK 
$CRTSK 
$CRTSK 
$DLTSK 
$SPTSK 
$SPTSK 
$CMDLN 
$ROGRP 
$CRGRP 
$DLGRP 
$SPGRP 
$ABGRQ 
$SUSPG 
$ACTVG 
$ABGRP 
$NPROC 
$ROBAT 
SRPTER 
SRPTER 
SASFIL 
SDSFIL 


«* 
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Monitor 
Call Number 


1020 
1025 
1030 
1035 
1040 
1050 
1051 
1055 
1056 
1057 
1060 
1061 
1062 
1063 
1064 
1065 
10A0 
10A5 
10B0 
10CO 
10D0 
1110 
1111 
1112 
1113 
1114 
1115 
1116 
1120 
1121 
1122 
1123 
1124 
1125 
1126 
1130 
1131 
1140 
1141 
1150 
1200 
1201 
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Function Description 


Get file 

Remove file 

Create file 

Release file 

Rename file/directory 

Open file (preserve) 

Open file (renew) 

Close file (normal) 

Close file (leave) 

Close file (unload) 

Get file information 

Test file I/O 

Test file for input 

Test file for output 

Wait for file input 

Wait for file output 

Create directory 

Release directory 

Change working directory 

Get working directory 

Expand pathname 

Read record 

Read record (with key) 

Read record (position = key) 
Read record (position > key) 
Read record (position = key) 
Read record (position forward) 
Read record (position backward) 
Write record 

Write record (with key) 

Write record (position = key) 
Write record (position > key) 
Write record (position > key) 
Write record (position forward) 
Write record (position backward) 
Delete record 

Delete record (with key) 
Rewrite record 

Rewrite record (with key) 
Unlock record 

Read block (normal) 

Read block (position to tape mark) 


Macro Call Name 


$GTFIL 
$RMFIL 
$CRFIL 
$RLFIL 
$RNFIL 
SOPFIL 
SOPFIL 
$CLFIL 


SCLFIL . 


SCLFIL 
$SGIFIL 
$TSFIL 
STIFIL 
STOFIL 
SWIFIL 
SWOFIL 
$CRDIR 
$RLDIR 
SCWDIR 
$GWDIR 
$XPATH 
$RDREC 
$RDREC 
$RDREC 
SRDREC 
$RDREC 
SRDREC 
SRDREC 
SWRREC 
SWRREC 
SWRREC 
SWRREC 
SWRREC 


~ $SWRREC 


SWRREC 
$DLREC 


S$DLREC 


SRWREC 
$RWREC 
SULREC 
$RDBLK 
$RDBLK 
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Monitor 
Call Number 
1202 
1203 
1204 
1210 
1211 
1220 
130A 
1400 
1401 
1402 
1403 
1404 
1406 
140B 
140C 
1501 
1502 
1503 
1504 
1505 
1506 
1507 
1509 
1702 
1703 
1704 
1 B00 
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Function Description | 


~ Read block (position to beginning of tape) 


Read block (position on blocks) 
Read block (position to end of tape) 
Write block (normal) 

Write block (write to tape mark) 
Wait block 

Set terminal characteristics 

User identification 

Task group person identification 
Account identifier 

Task group mode identification 
System identification 

Bound unit name 

Home directory name 

Task group input file name 

Accept message group 

Initiate message group | 

Receive 

Terminate message group 

Send 

Cancel message enclosure 

Count message group 

Wait on message group 

Cancel request for terminal 

Request terminal 

Release terminal 

Set dial 

Clock request block template - create 
Clock request block template - offsets 
Create file parameter block structure - offsets 
File information block - create 

Get file information file attributes 


block - offsets 
Get file information, key descriptors 


block - offsets 


Get file information, parameter structure 
block - offsets 


Get file, parameter structure block - offsets 


Input/Output request block template - create 
Input/Output request block template - 
offsets 
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‘Macto Call Name 


$RDBLK 
$RDBLK 
$RDBLK 
$WRBLK 
SWRBLK 
SWTBLK 
SSTTY 
$USRID 


$PERID _ 


$ACTID 
$MODID 
$SYSID 
$BUID 
SHDIR 
$TGIN 
SMACPT 
$MINIT 
SMRECV 
SMTMG 
$MSEND 
SMCME 
$MCMG 
$MW AIT 
SCANRQ 


~ $ROTML 


SRLTML 
SSDL 
$CRB 
SCRBD 
$CRPSB 
SFIB 
SGIFAB 


SGIKDB 


SGIPSB 


$GTPSB 


SIORB 
SIORBD 
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TABLE A-2 (CONT). SUMMARY OF EXECUTIVE MONITOR CALLS 


Monitor 
Call Number Function Description 
--- Parameter structure block - generate 
--- Request block template 
--- Return sequence - establish — 
Semaphore request block - create 
~- Semaphore request block template - offsets 
-- File information block - offsets 
--- 7 Task request block - create 
Template task request block - offsets 
--- Wait list - generate 
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Macro Call Name 


$PRBLK 
$RBD 
$RETRN 
$SRB 
$SRBD 
$TFIB 
$TRB 
$TRBD 
$WLIST 
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